Open Notebook MCP

打开笔记本MCP服务器

MCP（模型上下文协议）服务器，提供与 开放笔记本 API该服务器使Claude等AI助手能够管理笔记本、资源、笔记、搜索内容，并通过Open Notebook与AI模型进行交互。

特性

• 笔记本管理：创建、读取、更新和删除笔记本
• 来源管理：添加和管理内容源（链接、上传、文本）
• 票据管理：在笔记本中创建和组织笔记
• 搜索与人工智能：使用矢量/文本搜索搜索内容并提问
• 模型管理：配置和管理AI模型
• 聊天会话：创建和管理聊天对话
• 设置：访问和更新应用程序设置
• 渐进呈现：高效的工具发现 search_capabilities

安装

使用紫外线（推荐）

# 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

配置示例

对于使用默认“打开笔记本”设置的本地开发：

# .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

生产模式（流式HTTP）

对于远程部署：

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

与Claude Desktop一起使用

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "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（本地）和流式HTTP（远程）
• 错误处理：带有可操作提示的结构化错误消息
• 超时：所有API请求的30秒默认超时
• 认证：可选的承载令牌身份验证

发展

项目结构

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检查器测试服务器：

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. 添加a Capability 进入 CAPABILITIES 元组
2. 使用以下工具实现工具功能 @mcp.tool() 装饰器
3. 遵循命名约定： verb_noun （例如。， list_notebooks)
4. 包括适当的文档字符串和类型提示
5. 返回结构化响应 request_id

需求

• Python 3.12+
• 打开笔记本实例（本地或远程）
• 依赖关系： mcp[cli]>=1.23.2, httpx>=0.28.1

贡献

欢迎投稿！请确保：

• 遵循现有的代码结构和模式
• 将工具添加到 CAPABILITIES 索引
• 包含正确的类型提示和文档字符串
• 提交前与MCP检查员进行测试

许可证

有关详细信息，请参阅LICENSE文件。

链接

• 开放笔记本
• Open Notebook API参考
• 模型上下文协议
• FastMCP文档

支持

关于以下问题：

• 此MCP服务器：在此存储库中打开一个问题
• 打开笔记本本身：访问 打开笔记本存储库
• MCP协议：检查 MCP文件