Open Notebook × Model Context Protocol (MCP)将 AI 助手接入研究 Notebook 的完整集成指南【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebookOpen Notebook 不仅提供 Web 界面与 REST API还通过一套独立的 MCPModel Context Protocol服务端open-notebook-mcp让 Claude Desktop、VS Code 等 AI 客户端直接读写你的 Notebook、Source、Note 与 Chat。本文围绕 docs/5-CONFIGURATION/mcp-integration.md 展开并结合仓库源码说明其背后的 REST 端点与认证机制读完你可以在本地或远端实例上完整配置 MCP 服务并在任意 AI 助手内搜索研究内容、创建笔记与发起带上下文的对话。MCP 是什么为什么把 Open Notebook 接入它Model Context ProtocolMCP是一套开放的标准化协议它定义了一种AI 应用 ↔ 外部数据源/工具之间安全连接的方式。Open Notebook 的场景里数据与工具都来自你自建的实例notebooks、sources、notes、chat sessions、向量搜索与模型配置。MCP 服务端把这些能力以统一的工具接口暴露给客户端于是你可以直接在 Claude Desktop 或 VS Code 中读取你的 Notebook不离开 AI 助手即可检索研究资料文本与向量搜索以研究内容为上下文创建、管理 chat sessions在对话过程中即时生成 notes 与 insights借助完整的 Open Notebook API 自动化研究工作流。值得注意的是MCP 服务端只是翻译层它调用的是 Open Notebook 后端在 5055 端口上暴露的那套 REST API。所有路由都注册在 api/main.py 下的/api前缀例如 notebooks、search、models、notes、sources、chat、source_chat、settings 等 router。也就是说理解 MCP 工具能做什么本质上就是理解 API 的边界。前置条件让 Open Notebook API 先跑起来MCP 连接的是 REST 层因此首先要保证 API 在默认地址可访问本机开发Open Notebook 的 FastAPI 后端默认运行在http://localhost:5055交互式文档位于/docs健康检查位于GET /health返回{status:healthy}见 api/main.pyDocker Compose 部署在 docker-compose.yml 中已把容器的5055:5055映射到宿主机注释即为# REST API从源码运行可参考 docs/1-INSTALLATION/from-source.md其中也提供了uv run uvicorn api.main:app --host 0.0.0.0 --port 5055的方式与 docs/1-INSTALLATION/docker-compose.md。快速验证 API 是否就绪curl http://localhost:5055/health还需要本机装有uv以便uvx自动拉取并运行 MCP 服务端包下文详述。快速接入Claude DesktopMCP 服务端发布在 PyPI 上名为open-notebook-mcp因此 Claude Desktop 不需要手工安装它——Claude Desktop 会通过uvx按配置自动运行。macOS / Linux编辑~/Library/Application Support/Claude/claude_desktop_config.json{ mcpServers: { open-notebook: { command: uvx, args: [open-notebook-mcp], env: { OPEN_NOTEBOOK_URL: http://localhost:5055, OPEN_NOTEBOOK_PASSWORD: your_password_here } } } }Windows编辑%APPDATA%\Claude\claude_desktop_config.json{ mcpServers: { open-notebook: { command: uvx, args: [open-notebook-mcp], env: { OPEN_NOTEBOOK_URL: http://localhost:5055, OPEN_NOTEBOOK_PASSWORD: your_password_here } } } }保存后重启 Claude Desktop即可在对话中直接使用你的 Notebook。配置里有三个关键字段逐项说明字段含义注意事项command客户端用于启动 MCP 服务端的可执行文件固定为uvxuv 自带的包运行器要求机器已安装 uvargs传给命令的参数固定为包名open-notebook-mcpuvx会按需从 PyPI 解析安装并运行env传给 MCP 服务端的进程环境变量至少需要OPEN_NOTEBOOK_URL仅当后端启用了密码保护时才需要OPEN_NOTEBOOK_PASSWORD快速接入VS CodeCline 等 MCP 兼容扩展对于 VS Code把同样的服务端描述写入 VS Code 的 settings 或工作区的.vscode/mcp.json{ servers: { open-notebook: { command: uvx, args: [open-notebook-mcp], env: { OPEN_NOTEBOOK_URL: http://localhost:5055, OPEN_NOTEBOOK_PASSWORD: your_password_here } } } }Cline 等扩展读取该配置后即可发现并调用 Open Notebook 的工具。配置参考与认证机制MCP 服务端只依赖两个环境变量OPEN_NOTEBOOK_URLOpen Notebook API 的地址默认http://localhost:5055OPEN_NOTEBOOK_PASSWORD可选。仅当你的实例开启了密码保护时才需要且必须与后端配置的密码一致。连到远端服务器如果 Open Notebook 跑在局域网内另一台机器把 URL 指向它的 IPOPEN_NOTEBOOK_URL: http://192.168.1.100:5055如果实例部署在带域名的服务器上并经由反向代理把 API 暴露在/api路径可参考 docs/5-CONFIGURATION/reverse-proxy.mdOPEN_NOTEBOOK_URL: https://notebook.yourdomain.com/api后端密码保护的真实行为源码依据理解OPEN_NOTEBOOK_PASSWORD是否必须关键看后端认证中间件 api/auth.py。PasswordAuthMiddleware的实现要点从环境变量读取密码get_secret_from_env(OPEN_NOTEBOOK_PASSWORD)该工具同时支持 Docker secrets 形式的OPEN_NOTEBOOK_PASSWORD_FILE见 open_notebook/utils/encryption.py未设置密码 完全关闭认证没有硬编码的默认口令此时所有请求都会被放行一旦设置了密码除被排除的路径如/、/health、/docs、/openapi.json、/redoc、/api/auth/status、/api/config见 api/main.py外所有请求都必须携带Authorization: Bearer password头且校验使用secrets.compare_digest进行常量时间比较以避免时序侧信道见 api/auth.py。结论只要你的后端设置了OPEN_NOTEBOOK_PASSWORDMCP 配置的OPEN_NOTEBOOK_PASSWORD就必须填成同一个值否则 MCP 的每个 API 调用都会收到 401。反之如果后端完全没开认证这个变量可以省略。接入后可以做什么连接成功后可以直接用自然语言指挥 Claude 或其他 AI 助手例如Search my research notebooks for information about [topic]Create a new note summarizing the key points from our conversationList all my notebooksStart a chat session about [specific source or topic]What sources do I have in my [notebook name] notebook?Add this PDF to my research notebookShow me all notes in [notebook name]MCP 服务端提供的这些工具把 Open Notebook 的整组 API 能力带进了助手侧让你不必切出 IDE 或桌面应用即可管理研究资料。MCP 服务端暴露的工具与对应 REST APIMCP 服务端背后的每个工具都会转发成一次 REST 调用。下面按领域列出仓库中对应的真实端点方便你在排查问题时直接对齐 api/routers 中的实现。Notebooks列出 notebooksGET /api/notebooks支持archived过滤与order_by白名单排序见 api/routers/notebooks.py获取 notebook 详情GET /api/notebooks/{notebook_id}同时会记录last_viewed_at创建 notebookPOST /api/notebooks更新 notebookPUT /api/notebooks/{notebook_id}删除 notebookDELETE /api/notebooks/{notebook_id}支持delete_exclusive_sources级联参数并可先用GET /api/notebooks/{notebook_id}/delete-preview预览删除影响Sources列出 notebook 内的 sourcesGET /api/sources获取 source 详情GET /api/sources/{source_id}添加新 source链接 / 文件上传 / 文本等类型支持同步或异步处理POST /api/sourcesmultipart 表单解析入口另保留POST /api/sources/json兼容端点见 api/routers/sources.py更新 source 元数据PUT /api/sources/{source_id}删除 sourceDELETE /api/sources/{source_id}附加能力GET /api/sources/{source_id}/status查询处理状态、POST /api/sources/{source_id}/retry重试失败处理Notes列出 notebook 中的 notesGET /api/notes获取 note 详情GET /api/notes/{note_id}创建 notePOST /api/notes更新 notePUT /api/notes/{note_id}删除 noteDELETE /api/notes/{note_id}以上端点的完整实现见 api/routers/notes.py。Chat创建 chat sessionPOST /api/chat/sessions列出 chat sessionsGET /api/chat/sessions获取会话历史GET /api/chat/sessions/{session_id}/messages更新 / 删除 sessionPUT /api/chat/sessions/{session_id}、DELETE /api/chat/sessions/{session_id}附加能力POST /api/chat/execute直接执行对话、POST /api/chat/context构建上下文对应实现见 api/routers/chat.py。如果你需要针对某个 source 发起带引文的 source chat端点是POST /api/sources/{source_id}/chat/sessions与POST /api/sources/{source_id}/chat/sessions/{session_id}/messages见 api/routers/source_chat.py。Search向量 文本混合检索、按 notebook 过滤POST /api/search附加能力POST /api/search/ask、POST /api/search/ask/simple对应实现见 api/routers/search.py。Models列出已配置模型GET /api/models创建模型配置POST /api/models管理默认模型GET/PUT /api/models/defaults发现与同步模型POST /api/models/sync、GET /api/models/providers等对应实现见 api/routers/models.py。Settings读取应用设置GET /api/settings更新设置PUT /api/settings对应实现见 api/routers/settings.py。服务端的获取渠道open-notebook-mcp遵循标准 MCP 协议发布由 Epochal 团队维护可以从以下渠道获取官方 MCP Registry检索关键词open-notebookPyPI包名open-notebook-mcp这正是uvx open-notebook-mcp能自动运行的原因源码仓库Epochal-dev 组织下的 open-notebook-mcp 项目欢迎提交 contribution、issue 与 feature request。故障排查如果连接失败按顺序检查确认OPEN_NOTEBOOK_URL拼写正确且从当前机器可达先执行curl http://localhost:5055/health或对应 URL验证 API 本身在线若开启了密码保护确认OPEN_NOTEBOOK_PASSWORD与后端OPEN_NOTEBOOK_PASSWORD完全一致注意没有设置密码时后端是完全放行的MCP 端也无需该变量连接远端服务器时确认宿主机 5055 端口已映射且可访问Docker 场景对应5055:5055的端口映射见 docker-compose.yml检查防火墙/安全组是否放行到目标端口若通过域名访问还要确认反向代理正确把/api前缀转发到后端配置修改后务必完全重启 Claude Desktop / VS CodeMCP 服务端才会重新以新环境变量启动。安全建议MCP 本质上把 Open Notebook 的完整写权限暴露给了 AI 客户端因此注意默认的http://localhost:5055仅适合本机使用不要直接把未加密、未鉴权的实例端口暴露到公网强烈建议为 API 设置OPEN_NOTEBOOK_PASSWORD让 MCP 的所有请求都经过 Bearer 认证对远端部署优先走 HTTPS并参考 docs/5-CONFIGURATION/reverse-proxy.md 与 docs/5-CONFIGURATION/security.md 检查传输层与访问控制完整的受支持环境变量清单可查阅 docs/5-CONFIGURATION/environment-reference.md。与其他 MCP 客户端配合open-notebook-mcp遵循标准 MCP 协议因此不限于 Claude Desktop任何 MCP 兼容客户端都可以通过相同的配置结构接入。不同客户端对服务端配置的存放位置与字段命名略有差异例如有的用mcpServers有的用servers以你所使用客户端的官方文档为准核心的command/args/env三者语义不变。相关文档配置总览docs/5-CONFIGURATION/index.md反向代理与安全部署docs/5-CONFIGURATION/reverse-proxy.md、docs/5-CONFIGURATION/security.md安装与端口说明docs/1-INSTALLATION/docker-compose.md、docs/1-INSTALLATION/from-source.mdREST API 参考docs/7-DEVELOPMENT/api-reference.md核心概念Notebook / Source / Note / Chatdocs/2-CORE-CONCEPTS/notebooks-sources-notes.md【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考