open-notebook

Open Notebook MCP サーバー

Open Notebook API と連携するツールを提供する MCP（Model Context Protocol）サーバーです。このサーバーを使うと、Claude などの AI アシスタントから、Open Notebook を通じてノートブックやソース、ノートの管理、コンテンツの検索、AI モデルとのやり取りができます。

機能

• ノートブックの管理：ノートブックの作成、読み取り、更新、削除
• ソースの管理：コンテンツソース（リンク、アップロード、テキスト）の追加と管理
• ノートの管理：ノートブック内でのノートの作成と整理
• 検索と AI：ベクトル検索／テキスト検索によるコンテンツ検索と質問
• モデルの管理：AI モデルの設定と管理
• チャットセッション：チャットでの会話の作成と管理
• 設定：アプリケーション設定の参照と更新
• 段階的な情報開示：search_capabilities による効率的なツールの検出

インストール

uv を使用する場合（推奨）

# Clone the repository
git clone https://github.com/PiotrAleksander/open-notebook-mcp.git
cd open-notebook-mcp

# Install with uv
uv sync

pip を使用する場合

pip install -e .

設定

Open Notebook インスタンスに接続するには、サーバーの設定が必要です。

環境変数

.env ファイルを作成するか、次の環境変数を設定します。

# Required: URL of your Open Notebook instance
OPEN_NOTEBOOK_URL=http://localhost:5055

# Optional: Authentication password (if APP_PASSWORD is set in Open Notebook)
OPEN_NOTEBOOK_PASSWORD=your_password_here

# Optional: Transport configuration (default: stdio)
MCP_TRANSPORT=stdio  # or streamable-http for remote deployment

設定例

Open Notebook のデフォルト設定を使ったローカル開発の場合：

# .env
OPEN_NOTEBOOK_URL=http://localhost:5055

Open Notebook で認証を設定している場合：

# .env
OPEN_NOTEBOOK_URL=http://localhost:5055
OPEN_NOTEBOOK_PASSWORD=my_secure_password

使用方法

サーバーの実行

開発モード（STDIO）

AI アシスタントとローカルで使用する場合：

uv run open-notebook-mcp

または、MCP CLI を使用します。

mcp dev src/open_notebook_mcp/server.py

本番モード（Streamable HTTP）

リモート環境にデプロイする場合：

MCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 uv run open-notebook-mcp

Claude Desktop での使用

Claude Desktop の設定（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "open-notebook": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/open-notebook-mcp",
        "open-notebook-mcp"
      ],
      "env": {
        "OPEN_NOTEBOOK_URL": "http://localhost:5055",
        "OPEN_NOTEBOOK_PASSWORD": "your_password_if_needed"
      }
    }
  }
}

利用可能なツールの検出

このサーバーは段階的な情報開示を実装しています。search_capabilities ツールを使って、利用可能な機能を検出します。

# Get a summary of all tools
search_capabilities(query="", detail="summary", limit=50)

# Search for specific functionality
search_capabilities(query="notebook", detail="summary", limit=10)

# Get full details for a specific tool
search_capabilities(query="create_notebook", detail="full", limit=1)

ワークフローの例

ノートブックの作成と管理

# Create a new notebook
result = create_notebook(
    name="AI Research",
    description="Research on AI applications"
)
notebook_id = result["notebook"]["id"]

# List all notebooks
notebooks = list_notebooks(archived=False, limit=20)

# Update a notebook
update_notebook(
    notebook_id=notebook_id,
    name="AI Research (Updated)"
)

# Get a specific notebook
notebook = get_notebook(notebook_id=notebook_id)

ソースの追加

# Add a web source
source = create_source(
    notebook_id=notebook_id,
    type="link",
    url="https://example.com/ai-article",
    title="AI Research Article",
    embed=True  # Generate embeddings
)

# List sources in a notebook
sources = list_sources(notebook_id=notebook_id, limit=20)

ノートの作成

# Create a note
note = create_note(
    notebook_id=notebook_id,
    title="Key Findings",
    content="Important insights about AI applications...",
    topics=["AI", "Research"]
)

# Update a note
update_note(
    note_id=note["note"]["id"],
    content="Updated insights..."
)

検索と質問

# Search content
results = search(
    query="artificial intelligence",
    type="vector",
    notebook_id=notebook_id,
    limit=10
)

# List available models first
models = list_models(limit=50)
model_id = models["models"][0]["id"]

# Ask a question
answer = ask_simple(
    question="What are the main AI applications mentioned?",
    strategy_model=model_id,
    answer_model=model_id,
    final_answer_model=model_id,
    notebook_id=notebook_id
)

チャットセッション

# Create a chat session
session = create_chat_session(
    notebook_id=notebook_id,
    title="Research Discussion"
)
session_id = session["session"]["id"]

# Build context
context = get_chat_context(notebook_id=notebook_id)

# Send a message
response = execute_chat(
    session_id=session_id,
    message="What are the key insights from my research?",
    context=context["context"]
)

# Get session history
history = get_chat_session(session_id=session_id)

利用可能なツール

サーバーは複数のカテゴリーにわたる 39 個のツールを提供します。

メタツール

• search_capabilities - 段階的なツールの検出

ノートブック（5 個のツール）

• list_notebooks、get_notebook、create_notebook、update_notebook、delete_notebook

ソース（5 個のツール）

• list_sources、get_source、create_source、update_source、delete_source

ノート（5 個のツール）

• list_notes、get_note、create_note、update_note、delete_note

検索（3 個のツール）

• search、ask_question、ask_simple

モデル（5 個のツール）

• list_models、get_model、create_model、delete_model、get_default_models

チャット（7 個のツール）

• list_chat_sessions、create_chat_session、get_chat_session、update_chat_session、delete_chat_session、execute_chat、get_chat_context

設定（2 個のツール）

• get_settings、update_settings

アーキテクチャ

このサーバーは MCP のベストプラクティスに準拠しています。

• 段階的な情報開示：search_capabilities を使い、コンテキストの使用量を最小限に抑えます
• コンテキスト効率：デフォルトでは出力を小さくし、上限を指定するパラメーターを用意しています
• デュアルトランスポート：STDIO（ローカル）と Streamable HTTP（リモート）の両方に対応しています
• エラー処理：対応の手がかりを含む構造化されたエラーメッセージを提供します
• タイムアウト：すべての API リクエストにデフォルトで 30 秒のタイムアウトを設定しています
• 認証：任意の Bearer トークン認証に対応しています

開発

プロジェクト構成

open-notebook-mcp/
├── src/
│   └── open_notebook_mcp/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── tests/                      # (to be added)
├── pyproject.toml
├── README.md
└── .env.example

テスト

MCP Inspector を使ってサーバーをテストします。

mcp dev src/open_notebook_mcp/server.py

または

npx @modelcontextprotocol/inspector uv --directory ./src/open_notebook_mcp "run" "server.py"

インタラクティブなインスペクターが開き、次の操作ができます。

1. 利用可能なツールの確認
2. ツール呼び出しのテスト
3. 応答の確認
4. エラーのデバッグ

新しいツールの追加

新しいツールを追加するには、次の手順に従います。

1. CAPABILITIES タプルに Capability エントリを追加します
2. @mcp.tool() デコレーターを使用してツール関数を実装します
3. 命名規則 verb_noun（例：list_notebooks）に従います
4. 適切な docstring と型ヒントを記述します
5. request_id を含む構造化レスポンスを返します

要件

• Python 3.12+
• Open Notebook インスタンス（ローカルまたはリモート）
• 依存関係：mcp[cli]>=1.23.2、httpx>=0.28.1

コントリビューション

コントリビューションを歓迎します。次の点をご確認ください。

• 既存のコード構造とパターンに従う
• CAPABILITIES インデックスにツールを追加する
• 適切な型ヒントと docstring を記述する
• 提出前に MCP Inspector でテストする

ライセンス

詳細は LICENSE ファイルをご覧ください。

リンク

• Open Notebook
• Open Notebook API リファレンス
• Model Context Protocol
• FastMCP ドキュメント

サポート

次の問題については、それぞれの窓口をご利用ください。

• この MCP サーバー：このリポジトリで issue を作成してください
• Open Notebook 自体：Open Notebook リポジトリをご覧ください
• MCP プロトコル：MCP ドキュメントをご確認ください