Notion MCP Server (Official)

什么是 Notion MCP Server (Official)？

Notion MCP Server (Official) 是 Notion 官方开源、可自托管的 notion mcp server（@notionhq/notion-mcp-server）。它把 Notion API 转换成 MCP 工具，让 AI 客户端可以搜索、读取、创建和更新页面、数据库、评论和区块。

Notion 现已将该仓库标注为不再积极维护，并推荐改用其托管版 Remote Notion MCP（https://mcp.notion.com/mcp）。本页同时介绍两者：本条目所描述的本地服务器，以及 Notion 推荐用户使用的托管端点。

如何使用 Notion MCP Server (Official)？

可从以下两种方式中选择一种：

• Remote Notion MCP（Notion 推荐）：无需安装。在客户端中添加 https://mcp.notion.com/mcp，然后通过 OAuth 登录即可。它沿用你在 Notion 中已有的权限。
• 本地服务器（本仓库）：通过 npx 或 Docker 运行。它使用 internal integration token（ntn_...）认证，需要你自己把页面共享给该 integration。

本地配置：token 与页面访问权限

1. 打开 https://www.notion.so/profile/integrations，创建一个 internal integration。
2. 在 integration 的 Access 标签页中，选择它可以使用的页面和数据库。也可以打开某个页面，点击右上角的三个点，选择 Connect to integration。
3. 复制 integration secret。如需只读权限，在 Capabilities 中只勾选 "Read content"。

Claude Desktop

将服务器添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

使用 Docker 的用户也可以改用官方镜像 mcp/notion（详见 README）。

Cursor

本地服务器：把同样的 JSON 写入 .cursor/mcp.json。托管服务器则使用：

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

然后在 Cursor 侧边栏中打开 Customize，启用 Notion 并完成 OAuth 流程。

Claude Code

Notion 文档给出了 Claude Code 连接托管端点的方式：

claude mcp add --transport http notion https://mcp.notion.com/mcp

然后在 Claude Code 中运行 /mcp，按提示完成 OAuth 流程。

VS Code

创建 .vscode/mcp.json：

{
  "servers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

在命令面板中运行 MCP: List Servers，启动 Notion 并登录。

Codex

将以下内容添加到 ~/.codex/config.toml，然后运行 codex mcp login notion：

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

本地服务器的 README 还提供了 Zed 和 GitHub Copilot CLI（~/.copilot/mcp-config.json）的配置。

Notion MCP Server (Official) 的主要功能

• 由 Notion（makenotion）以 MIT 许可证发布，npm 包名为 @notionhq/notion-mcp-server，Docker Hub 镜像为 mcp/notion。
• 工具由 Notion 的 OpenAPI 规范自动生成，每个工具对应一个 Notion API 端点。
• 2.0 版本使用 Notion API 2025-09-03 及其 data sources 模型（用 data_source_id 取代 database_id）。
• 页面内容可以用 Markdown 读取和编辑，比区块 JSON 节省大量 token。
• 默认使用 STDIO 传输；通过 --transport http 可启用 Streamable HTTP，此时需要 bearer token（--auth-token 或 AUTH_TOKEN）。
• --enable-token-passthrough 允许一个 HTTP 部署通过每个会话的 Notion-Token 请求头服务多个 integration。
• 有意不开放部分操作，例如无法通过它删除数据库。

Notion MCP Server (Official) 工具

本地服务器的工具可分为以下几组：

• 搜索与用户：post-search 搜索页面和 data source；get-users、get-user 和 get-self 用于查询工作区成员和机器人用户。
• 页面：post-page、retrieve-a-page、patch-page、retrieve-a-page-property 和 move-page 用于创建、读取、更新和移动页面。
• Markdown 内容：retrieve-page-markdown 和 update-page-markdown 以 Markdown 形式读取和编辑整个页面。
• 区块：get-block-children、patch-block-children、retrieve-a-block、update-a-block 和 delete-a-block 逐个区块处理页面内容。
• 数据库与 data source：query-data-source（支持筛选和排序）、retrieve-a-data-source、create-a-data-source、update-a-data-source、list-data-source-templates 和 retrieve-a-database。
• 评论：create-a-comment 和 retrieve-a-comment。

托管版 Remote Notion MCP 提供另一套面向 AI agent 的工具，例如 notion-search、notion-fetch、notion-create-pages、notion-update-page 和 notion-query-data-sources。

Notion MCP Server (Official) 的使用场景

• 在对话中给页面添加评论："Comment 'Hello MCP' on page 'Getting started'"。客户端会先调用搜索，再调用评论端点。
• 在父页面下创建页面："Add a page titled 'Notion MCP' to page 'Development'"。
• 编码时按 ID 读取页面作为上下文："Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2"。
• 用筛选和排序查询任务或 bug 数据库，并汇总结果。
• 通过 Markdown 工具改写会议记录或需求文档，无需处理区块 JSON。

Notion MCP Server (Official) 与替代方案对比

• Remote Notion MCP（托管版）：Notion 推荐的 mcp notion 方案。它使用 OAuth 和你自己的权限，支持跨 Notion 及已连接应用的语义搜索，并且持续获得支持，无需本地进程。部分功能（如 AI 搜索和用于无界面场景的 MCP token）需要 Business 或 Enterprise 套餐。
• 本地服务器（本仓库）：适合需要基于 token 的无界面访问或希望自托管的场景。Notion 表示它不再获得积极支持，未来可能停止。
• 社区服务器：例如 awkoy/notion-mcp-server，这是一个非官方项目，npm 包名为 notion-mcp-server，与 Notion 的代码库无关。

Notion MCP Server (Official) 常见问题排查

• 找不到页面或数据库：integration 只能看到共享给它的内容。在 integration 的 Access 标签页中添加该页面，或使用 Connect to integration。
• 旧的数据库工具不见了：v2.0 用 query-data-source、update-a-data-source 和 create-a-data-source 取代了 post-database-query、update-a-database 和 create-a-database。请更新硬编码了旧名称的提示词。
• HTTP 请求被拒绝：Streamable HTTP 要求每个请求都带有 Authorization: Bearer <token>。未指定 --auth-token 时，服务器会把自动生成的 token 写入一个临时文件。除非在隔离网络中，否则不要使用 --unsafe-disable-auth。
• 客户端只支持本地服务器：仍可以通过 mcp-remote 桥接连接托管服务器："command": "npx", "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]。
• 托管版 OAuth 失败：断开并重新连接客户端，然后检查你在目标工作区中的访问权限。工作区访客（guest）无法连接。