open-notebook

Open Notebook MCP 服务

一个 MCP（Model Context Protocol）服务，提供与 Open Notebook API 交互的工具。该服务可让 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. 添加恰当的文档字符串和类型提示
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 参考
• Model Context Protocol
• FastMCP 文档

支持

以下问题请联系：

• 此 MCP 服务：在此仓库中提交 issue
• Open Notebook 本身：访问 Open Notebook 仓库
• MCP 协议：查看 MCP 文档