Open Notebook MCP

🚀 Open Notebook MCP Server

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

✨ 主な機能

• ノートブック管理：ノートブックの作成、閲覧、更新、削除が可能
• ソース管理：コンテンツソース（リンク、アップロード、テキスト）の追加と管理
• ノート管理：ノートブック内でノートの作成と整理
• 検索とAI：ベクトル/テキスト検索を使用したコンテンツ検索と質問応答
• モデル管理：AIモデルの設定と管理
• チャットセッション：チャット会話の作成と管理
• 設定：アプリケーション設定のアクセスと更新
• 漸進的開示：search_capabilitiesによる効率的なツール発見

📦 インストール

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

# リポジトリをクローン
git clone https://github.com/PiotrAleksander/open-notebook-mcp.git
cd open-notebook-mcp

# uvでインストール
uv sync

pipを使用する場合

pip install -e .

📚 ドキュメント

設定

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

環境変数

.envファイルを作成するか、以下の環境変数を設定してください。

# 必須: Open NotebookインスタンスのURL
OPEN_NOTEBOOK_URL=http://localhost:5055

# オプション: 認証パスワード（Open NotebookでAPP_PASSWORDが設定されている場合）
OPEN_NOTEBOOK_PASSWORD=your_password_here

# オプション: トランスポート設定（デフォルト: stdio）
MCP_TRANSPORT=stdio  # リモートデプロイの場合はstreamable-http

設定例

デフォルトの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ツールを使用して、利用可能な機能を発見できます。

# すべてのツールの概要を取得
search_capabilities(query="", detail="summary", limit=50)

# 特定の機能を検索
search_capabilities(query="notebook", detail="summary", limit=10)

# 特定のツールの詳細を取得
search_capabilities(query="create_notebook", detail="full", limit=1)

ワークフロー例

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

# 新しいノートブックを作成
result = create_notebook(
    name="AI Research",
    description="Research on AI applications"
)
notebook_id = result["notebook"]["id"]

# すべてのノートブックをリスト表示
notebooks = list_notebooks(archived=False, limit=20)

# ノートブックを更新
update_notebook(
    notebook_id=notebook_id,
    name="AI Research (Updated)"
)

# 特定のノートブックを取得
notebook = get_notebook(notebook_id=notebook_id)

ソースの追加

# ウェブソースを追加
source = create_source(
    notebook_id=notebook_id,
    type="link",
    url="https://example.com/ai-article",
    title="AI Research Article",
    embed=True  # 埋め込みを生成
)

# ノートブック内のソースをリスト表示
sources = list_sources(notebook_id=notebook_id, limit=20)

ノートの作成

# ノートを作成
note = create_note(
    notebook_id=notebook_id,
    title="Key Findings",
    content="Important insights about AI applications...",
    topics=["AI", "Research"]
)

# ノートを更新
update_note(
    note_id=note["note"]["id"],
    content="Updated insights..."
)

検索と質問

# コンテンツを検索
results = search(
    query="artificial intelligence",
    type="vector",
    notebook_id=notebook_id,
    limit=10
)

# 利用可能なモデルをリスト表示
models = list_models(limit=50)
model_id = models["models"][0]["id"]

# 質問を投げる
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
)

チャットセッション

# チャットセッションを作成
session = create_chat_session(
    notebook_id=notebook_id,
    title="Research Discussion"
)
session_id = session["session"]["id"]

# コンテキストを構築
context = get_chat_context(notebook_id=notebook_id)

# メッセージを送信
response = execute_chat(
    session_id=session_id,
    message="What are the key insights from my research?",
    context=context["context"]
)

# セッション履歴を取得
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秒のデフォルトタイムアウト
• 認証：オプションのベアラートークン認証

開発

プロジェクト構造

open-notebook-mcp/
├── src/
│   └── open_notebook_mcp/
│       ├── __init__.py
│       └── server.py          # 主なMCPサーバーの実装
├── tests/                      # (追加予定)
├── 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. 適切なドキュメント文字列と型ヒントを含める
5. request_idを含む構造化された応答を返す

要件

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

コントリビューション

コントリビューションは大歓迎です！以下を確認してください。

• 既存のコード構造とパターンに従う
• CAPABILITIESインデックスにツールを追加する
• 適切な型ヒントとドキュメント文字列を含める
• 提出する前にMCP Inspectorでテストする

📄 ライセンス

詳細はLICENSEファイルを参照してください。

リンク

• Open Notebook
• Open Notebook API Reference
• Model Context Protocol
• FastMCP Documentation

サポート

以下の問題に関しては：

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