Notion MCP Server

[!NOTE]

我们推出了 Notion MCP，一个远程 MCP 服务器，具有以下改进：

• 通过标准 OAuth 即可轻松安装。无需再折腾 JSON 或 API 令牌。
• 为 AI 代理量身打造的强大工具，包括以 Markdown 编辑页面。这些工具在设计时充分考虑了令牌消耗的优化。

了解更多并开始使用，请访问 Notion MCP 文档。

我们优先并仅对 Notion MCP（远程）提供积极支持。因此：

• 我们未来可能会停止维护此本地 MCP 服务器仓库。
• 此处的 Issue 和 Pull Request 不会得到积极监控。
• 请勿在此处提交与远程 MCP 相关的 Issue；请联系 Notion 支持。

本项目为 Notion API 实现了一个 MCP 服务器。

---

⚠️ 2.0.0 版本的破坏性变更

2.0.0 版本迁移至 Notion API 2025-09-03，该版本引入了数据源（data source）作为数据库的主要抽象。

变更内容

已移除的工具（3 个）：

• post-database-query - 由 query-data-source 替代
• update-a-database - 由 update-a-data-source 替代
• create-a-database - 由 create-a-data-source 替代

新增工具（7 个）：

• query-data-source - 使用过滤器和排序查询数据源（数据库）
• retrieve-a-data-source - 获取数据源的元数据和架构
• update-a-data-source - 更新数据源属性
• create-a-data-source - 创建新的数据源
• list-data-source-templates - 列出数据源中可用的模板
• move-page - 将页面移动到不同的父位置
• retrieve-a-database - 获取数据库元数据，包括其数据源 ID

参数变更：

• 所有数据库操作现在使用 data_source_id 而不是 database_id
• 搜索过滤器值从 ["page", "database"] 更改为 ["page", "data_source"]
• 页面创建现在支持 page_id 和 database_id 两种父级（用于数据源）

我需要迁移吗？

无需更改代码。 MCP 工具会在服务器启动时自动发现。当您升级到 v2.0.0 时，AI 客户端将自动看到新的工具名称和参数。旧的数据库工具将不再可用。

如果您硬编码了引用旧数据库工具的工具名称或提示词，请更新为使用新的数据源工具：

| 旧工具（v1.x） | 新工具（v2.0） | 参数变更 | | -------------- | --------------- | ---------------- | | post-database-query | query-data-source | database_id → data_source_id | | update-a-database | update-a-data-source | database_id → data_source_id | | create-a-database | create-a-data-source | 无变更（使用 parent.page_id） |

注意： retrieve-a-database 仍然可用，并返回数据库元数据，包括数据源 ID 列表。使用 retrieve-a-data-source 获取特定数据源的架构和属性。

工具总数现在为：22 个（v1.x 中为 19 个）

---

页面内容作为 Markdown

服务器提供两个工具，用于将页面内容作为增强型 Markdown（而不是块 JSON）进行处理，这对 AI 代理来说在令牌消耗上要高效得多：

• retrieve-page-markdown — 将页面的完整内容读取为 Markdown（GET /v1/pages/{page_id}/markdown）。传入 include_transcript: true 可内联会议记录转录文本。
• update-page-markdown — 使用 Markdown 编辑页面内容（PATCH /v1/pages/{page_id}/markdown）。优先使用 replace_content 覆盖整个页面，或使用 update_content 进行有针对性的查找替换编辑。

这些端点需要 Notion API 版本 2026-03-11。服务器现在从 OpenAPI 规范中按操作获取 Notion-Version 头，因此这些工具使用 2026-03-11，而其余 API 继续使用 2025-09-03 — 无需配置。如果您通过 OPENAPI_MCP_HEADERS 自行设置 Notion-Version，您的值将优先生效。

---

安装

1. 在 Notion 中设置集成

前往 https://www.notion.so/profile/integrations 创建一个新的内部集成，或选择一个现有的集成。

虽然我们限制了 Notion API 的暴露范围（例如，您将无法通过 MCP 删除数据库），但将工作区数据暴露给 LLM 仍存在非零风险。注重安全的用户可能希望进一步配置集成的_功能_。

例如，您可以通过在"配置"选项卡中仅授予"读取内容"访问权限来创建只读集成令牌：

![Notion Integration To…