Open Notebook MCP

🚀 Open Notebook MCP 服務器

Open Notebook MCP 服務器是一個基於 MCP（模型上下文協議）的服務器，它提供了與 Open Notebook API 進行交互的工具。藉助該服務器，像 Claude 這樣的 AI 助手能夠管理筆記本、來源、筆記，搜索內容，並通過 Open Notebook 與 AI 模型進行交互。

🚀 快速開始

安裝

使用 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"
      }
    }
  }
}

✨ 主要特性

• 筆記本管理：創建、讀取、更新和刪除筆記本。
• 來源管理：添加和管理內容來源（鏈接、上傳文件、文本）。
• 筆記管理：在筆記本中創建和組織筆記。
• 搜索與 AI：使用向量/文本搜索功能搜索內容並提問。
• 模型管理：配置和管理 AI 模型。
• 聊天會話：創建和管理聊天對話。
• 設置：訪問和更新應用程序設置。
• 漸進式展示：使用 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 個工具，分為多個類別：

架構

此服務器遵循 MCP 最佳實踐：

• 漸進式展示：使用 search_capabilities 最小化上下文使用。
• 上下文效率：默認輸出較小，帶有限制參數。
• 雙傳輸：支持 STDIO（本地）和 Streamable HTTP（遠程）。
• 錯誤處理：帶有可操作提示的結構化錯誤消息。
• 超時：所有 API 請求的默認超時時間為 30 秒。
• 認證：可選的 Bearer 令牌認證。

開發

項目結構

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. 遵循命名約定：動詞_名詞（例如，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 參考
• 模型上下文協議
• FastMCP 文檔

🛠️ 支持

對於以下相關問題：

• 此 MCP 服務器：在此倉庫中創建一個問題。
• Open Notebook 本身：訪問 Open Notebook 倉庫。
• MCP 協議：查看 MCP 文檔。