适合谁
- 已经在 Notion 中管理文档/知识库,希望通过 AI 客户端(Claude Desktop、Cursor 等)直接操作 Notion 内容的团队或个人
- 需要自建/自托管本地 MCP 服务器,而非使用远程托管方案的开发者
- 需要脚本化或代理化处理 Notion 数据库记录的自动化工作流
N
64FMRS · C
该项目是 Notion 官方维护的开源本地 MCP 服务器,功能覆盖页面、数据库(数据源)、评论及 Markdown 页面编辑,文档详尽且随 API 更新持续演进(如 v2.0.0 的数据源迁移)。但官方已明确表示优先支持全新的远程托管版 Notion MCP,并暗示该本地仓库未来可能被弃用、Issue 与 PR 不再被积极处理,评估长期使用时需考虑这一点。
本仓库是 Notion 官方维护的本地 MCP 服务器,基于 Notion API 实现,通过标准输入输出(stdio)或可流式传输的 HTTP 与 AI 客户端通信。它提供搜索、页面创建与评论、数据库(数据源)查询与更新等工具,并新增了以 Markdown 形式读写整页内容的工具(需要 Notion API 版本 2026-03-11),相比原始 block JSON 更省 token。README 中明确说明 Notion 已推出全新的远程托管版 “Notion MCP”(支持标准 OAuth 安装),并优先支持该远程版本;本地版本未来可能被弃用,Issue 和 PR 也不会被积极处理。v2.0.0 版本迁移到 Notion API 2025-09-03,用“数据源(data source)”概念取代原来的数据库操作工具,并将参数由 database_id 改为 data_source_id。
工具能力
query-data-source
使用过滤条件和排序查询某个数据源(数据库)。
retrieve-a-data-source
获取某个数据源的元数据与结构(schema)。
update-a-data-source
更新数据源的属性/结构。
create-a-data-source
在数据库下创建新的数据源。
list-data-source-templates
列出某个数据源中可用的页面模板。
move-page
将页面移动到另一个父页面或数据库下。
retrieve-a-database
获取数据库的元数据,包括其包含的数据源 ID 列表。
retrieve-page-markdown
以 Markdown 格式读取页面的完整内容,可选择内联会议纪要转录文本。
update-page-markdown
使用 Markdown 编辑页面内容,可整页替换,也可做定向查找替换。
安装接入
- 在 Notion 的“我的集成”页面创建一个内部集成(Integration),并获取以 ntn_ 开头的令牌;可在“Configuration”中限制其能力(如仅“读取内容”)以降低风险。2. 在需要开放给该集成的页面/数据库中,通过“Access”标签或页面右上角“Connect to integration”将其连接。3. 在客户端(如 Claude Desktop、Cursor、Zed、GitHub Copilot CLI)的 MCP 配置文件中添加通过 npx 或 Docker 启动的服务器条目,并设置 NOTION_TOKEN(或 OPENAPI_MCP_HEADERS)环境变量。4. 如需通过 HTTP 而非默认的 stdio 访问,可加 --transport http 并配置 --auth-token 或 AUTH_TOKEN 用于鉴权;多租户场景可启用 --enable-token-passthrough,让每个客户端在连接时通过 Notion-Token 请求头传入各自的 Notion 令牌。
claude_desktop_config.json
{"mcpServers":{"notionApi":{"command":"npx","args":["-y","@notionhq/notion-mcp-server"],"env":{"NOTION_TOKEN":"ntn_****"}}}}
选型与风险
不适合谁
- 希望使用标准 OAuth 免配置安装、且需要官方持续积极支持的用户(应使用 Notion 官方新推出的远程 Notion MCP)
- 不希望将 Notion 集成令牌交给本地运行的 LLM 客户端的用户
- 需要执行本集成未开放能力(如删除数据库)的场景
所需权限
- 一个 Notion 内部集成令牌(NOTION_TOKEN 或 OPENAPI_MCP_HEADERS 中的 Authorization),其权限范围由集成的 Capabilities 配置决定(可限制为只读)
- 仅限于显式连接到该集成的页面和数据库,而非整个工作区
- 使用 HTTP 传输时需要额外的 Bearer 鉴权令牌(--auth-token / AUTH_TOKEN)
- 网络访问 Notion API 的权限
风险与副作用
- 若集成被授予较广的读取/写入能力且连接了大量页面,相当于把这些工作区内容暴露给 LLM,存在数据泄露或误操作风险
- 使用 --unsafe-disable-auth 关闭 HTTP 鉴权后,服务器可能被通过 DNS 重绑定从访问者浏览器打开的网页间接访问,仅应在隔离网络中使用
- 开启多租户令牌透传(token passthrough)时,若未正确部署 TLS 及网关鉴权,存在 Notion 令牌被截获或错发给其他客户端的风险
- README 明确提示该本地仓库未来可能被弃用,Issue/PR 不再被积极处理,长期维护和安全更新没有保证
- 如果将 NOTION_TOKEN 或 OPENAPI_MCP_HEADERS 直接写入共享的客户端配置文件,存在密钥泄露风险
常见排障
- 确认 Notion 集成已被连接到目标页面/数据库(通过 Access 标签或页面的 Connect to integration)
- 确认集成的 Capabilities 权限(如是否开启写入)满足所调用工具的需求
- 检查客户端配置中 NOTION_TOKEN 或 OPENAPI_MCP_HEADERS 是否正确设置且未过期
- 升级到 v2.0.0 后,若脚本/提示词硬编码了旧的数据库工具名或 database_id 参数,需改为对应的数据源工具及 data_source_id
- 使用 Markdown 相关工具(retrieve-page-markdown / update-page-markdown)报错时,确认所用的 Notion-Version 请求头(默认由服务器针对该操作设为 2026-03-11)未被 OPENAPI_MCP_HEADERS 中的自定义值覆盖
- 使用 Streamable HTTP 传输时,确认请求头中的 Bearer 令牌与服务器的 --auth-token/AUTH_TOKEN 一致
使用场景
让 AI 助手搜索、读取和编辑 Notion 页面内容
让 AI 代理在 Notion 数据库(数据源)中查询、筛选、更新记录
为页面添加评论或创建新的子页面
以 Markdown 方式批量读写页面全文,降低 AI 交互的 token 开销
支持客户端
Claude Desktop完整支持
Cursor完整支持
Zed完整支持
GitHub Copilot CLI完整支持