Notion MCP Server

Notion MCP 服务 — 将 Claude、Cursor、VS Code 和 Codex 连接到 Notion

notion-mcp-server 是一款模型上下文协议（MCP）服务，只需一个令牌，即可让 Claude Code、Claude Desktop、Cursor、VS Code、Codex 及其他任何 MCP 客户端读写 Notion。你的 AI 可以用自然语言搜索、创建和编辑页面，查询数据库、发表评论并上传文件。

• 所有 Notion 套餐均支持令牌认证，包括免费套餐。 无需通过浏览器登录，因此也可在无头环境中运行：用于 CI、定时任务、后台 Agent，以及你自己的服务器。
• 占用的上下文少。 连接时，其三个工具共占用 1,005 个令牌，而 Notion 的开源服务占用 17,163 个令牌；读取页面返回的内容也小了 82%。查看基准测试 →
• 专为 Agent 打造。 支持带原子回滚和幂等键的批量写入、速率限制重试、Markdown 输入和输出，以及能告知模型如何修正调用的错误信息。

快速开始

1. 获取 Notion 令牌。 打开 app.notion.com/developers/tokens → + New token → 为令牌命名并选择工作区 → Create token → 复制 ntn_… 值。个人访问令牌可以访问 你 能看到的所有内容，无需逐页共享。无法创建令牌？请参阅其他令牌选项。

2. 安装。

npx add-mcp notion-mcp-server --env NOTION_TOKEN=ntn_paste_your_token_here

add-mcp 会查找你计算机上的 MCP 客户端，并为你选择的客户端写入配置：Claude Code、Claude Desktop、Cursor、VS Code、Codex、Gemini CLI、Cline、Windsurf、Zed 等。添加 -g 可为你的用户而非当前项目安装。

保留 --env 标志。若没有它，写入的条目将不包含令牌，每次调用都会因身份验证错误而失败。

也可以一键安装：

• Cursor： 替换生成条目中的 YOUR_NOTION_TOKEN。
• VS Code（Copilot Agent 模式）： 它会提示你输入令牌，并将其作为密钥保存。
• Claude Desktop： 双击 .mcpb 文件（或将其拖入“设置” →“扩展”），然后粘贴令牌。无需 Node.js。刚开始接触这些？分步指南会从零开始介绍。

使用 Claude Code？请改为将其作为插件安装。 此插件捆绑了 MCP 服务和 Notion 工作流技能，可教会 Claude 何时搜索、如何使用 where 筛选数据库，以及如何批量写入。安装时（或稍后使用 /plugin configure notion-mcp-server@awkoy）Claude Code 会提示你输入令牌，并将其保存在系统钥匙串中：

/plugin marketplace add awkoy/notion-mcp-server
/plugin install notion-mcp-server@awkoy

该插件运行与其自身版本匹配的 npm 发布版本，并且需要 Node.js 22 或更高版本。它还提供默认父页面和只读开关；详情请参阅插件的 README。

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "notion-mcp-server"],
      "env": { "NOTION_TOKEN": "ntn_paste_your_token_here" }
    }
  }
}

claude mcp add notion -s user -e NOTION_TOKEN=ntn_paste_your_token_here -- npx -y notion-mcp-server

[mcp_servers.notion]
command = "npx"
args = ["-y", "notion-mcp-server"]
env = { NOTION_TOKEN = "ntn_paste_your_token_here" }

claude mcp add notion -s user -e NOTION_TOKEN=ntn_paste_your_token_here \
  -- docker run --rm -i -e NOTION_TOKEN ghcr.io/awkoy/notion-mcp-server:latest

3. 试用。 在新聊天中输入：

“使用 Notion 创建一个名为‘来自我的 Agent 的问候’的页面，并添加一份包含三件今天要尝试的事情的清单。”

你的 AI 会调用 notion_write，并回复新页面的链接。

你可以提出哪些请求

• “在我的 Tasks 数据库中，找出 Status 为 ‘Doing’ 的所有行，并告诉我哪些已逾期。”
• “按新规范重命名这 50 个页面。” 一次批量调用，而不是 50 次。
• “使用我的 ‘Weekly review’ 模板创建一个页面，并填入这份摘要。”
• “重写那个规范页面：修正标题并添加代码示例。” 页面会以 Markdown 格式往返转换。
• “在昨天的会议记录中添加一段摘要评论。”
• “将这张示意图上传到设计页面。”
• “查看那份错误报告中的截图，告诉我哪里有问题。” 模型会直接获取图像。

应该使用哪个 Notion MCP？

若要在 claude.ai 或 ChatGPT 中与 Notion 聊天，只需点击一次即可连接 Notion 的托管连接器。当 Agent 需要无人值守运行、你的套餐不提供 MCP 令牌、需要控制上下文成本，或希望将其部署在自己的主机上时，请使用此服务。详细比较 →

配置

令牌：PAT 或内部集成

两者都使用同一个 NOTION_TOKEN 环境变量；区别仅在于获取方式。

• 谁可以创建 PAT。 工作区所有者始终可以创建。在 Free 和 Business 套餐中，默认只有所有者可以创建；在 Plus 套餐中，每位成员都可以创建；管理员可以更改 Business 和 Enterprise 套餐的策略。访客无法创建。
• 有效期和撤销。 创建时可选择有效期，最长为一年。可在同一个令牌页面撤销；撤销后会立即失效。详情请参阅：Notion 的 PAT 指南。
• 你能看到的页面却出现 object_not_found？ 这是因为某个内部集成尚未连接到该页面。请连接它，或改用 PAT。

环境变量

HTTP 变量见远程 / HTTP 传输。要从 v1 或 v2 升级？所有环境变量仍然有效；工具名称已更改，参见 MIGRATION.md。

限制操作

NOTION_READ_ONLY=true 会禁用所有写入操作。如需更精细的控制，NOTION_ALLOWED_OPERATIONS 和 NOTION_BLOCKED_OPERATIONS 接受以逗号分隔的操作名称或预设值：read、write、destructive（归档、移至废纸篓和删除），或某个类别（pages、blocks、databases、data_sources、views、comments、users、files）。阻止列表优先。

{ "env": { "NOTION_ALLOWED_OPERATIONS": "read" } }                       // read-only
{ "env": { "NOTION_BLOCKED_OPERATIONS": "destructive" } }                // everything except removals
{ "env": { "NOTION_ALLOWED_OPERATIONS": "read,append_blocks,add_page_comment" } }

被禁用的操作不会出现在工具架构中，因此模型不会看到它们。服务会在启动时打印解析后的配置，例如 Operation access: 22/48 enabled (allow=read; block=(none))。

如需在执行破坏性操作前征求确认，而不是直接阻止，请设置 NOTION_CONFIRM_DESTRUCTIVE=true：执行破坏性操作前，客户端会显示一个标明目标的“是/否”对话框。客户端必须支持 MCP elicitation。完整规则、各操作列表及按操作控制的限制见 docs/configuration.md。

文件

upload_file 接受 base64、公共 URL 或本地路径，最大为 NOTION_UPLOAD_MAX_BYTES（默认 1 GiB）。由于源由模型选择，服务端会对自行读取的两种源进行防护：

• 本地路径。 将 NOTION_UPLOAD_ROOT 设置为允许上传文件所在的目录；根目录之外的路径会被拒绝，包括符号链接。若未设置该变量，通过 HTTP 禁用路径源；通过 stdio 时，如果路径经过以点开头的文件或目录（~/.ssh、~/.aws、.env），或者位于系统目录或应用数据目录（/proc、/dev、~/Library、%APPDATA%）下，路径源也会被拒绝，因为 MCP 客户端会在这些位置保存令牌。NOTION_UPLOAD_ROOT=/ 会取消此限制。在根目录内，所有文件都可读取，包括 .env 和 .git，因此通过 HTTP 使用时，请选择一个只包含你愿意交给任何能调用该服务的人访问的文件的根目录。
• URL。 仅支持 http 和 https。每一跳（包括重定向）都必须解析为公共地址，因此环回地址、专用网络和云元数据端点都会被拒绝；将 NOTION_UPLOAD_ALLOW_PRIVATE_URLS=true 设为 true 可在内网使用。获取操作会在达到 NOTION_UPLOAD_URL_TIMEOUT_MS（30 s）时停止，或在正文大小超过限制时停止。

Notion 的签名文件 URL 每个约占 500 个令牌，并会在一小时内过期。NOTION_FILE_URLS=ref 会在响应中将它们替换为简短的 notion-file: 引用，get_file_url 和 get_image 可按需解析这些引用。了解引用的工作原理 →

远程 / HTTP 传输

该服务默认使用 stdio。设置 MCP_TRANSPORT=http，即可将其作为 Streamable HTTP 端点运行，供 Web 客户端、联网的 Agent 和共享部署使用：

MCP_TRANSPORT=http PORT=3000 NOTION_TOKEN=ntn_xxx npx -y notion-mcp-server
# -> notion-mcp-server vX.Y.Z running on http://127.0.0.1:3000/mcp

⚠️ 任何能访问 /mcp 的人都能以你的 NOTION_TOKEN 身份操作。 默认使用环回地址时，仅限本地进程访问。非环回地址的 HOST 若未设置 MCP_AUTH_TOKEN 则无法启动；同时也应在其前置 TLS。

通过 HTTP 使用时，除非设置了 NOTION_UPLOAD_ROOT，否则 upload_file 不接受本地路径，因为调用方可能不在服务所在的机器上。Base64 和 URL 源照常可用，参见文件。

claude mcp add --transport http notion https://your-host/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Docker、健康检查和协议版本：docs/http-transport.md。

工具和操作

无论你最终调用 46 项操作中的哪一项，都只需使用三个工具：notion_read 执行读取，notion_write 执行写入，notion_describe 返回某项操作的 JSON Schema 和可用示例。每个 ID 字段也接受 Notion URL，因此可以直接粘贴 Share → Copy link 提供的内容。调用示例、批处理选项和 MCP 资源：docs/operations.md。

按工具设置权限

读写分离让你可以一次性批准读取操作，并让写入操作始终需要提示确认。在 Claude Code 的 settings.json 中（notion 是你为服务指定的名称）：

{ "permissions": { "allow": ["mcp__notion__notion_read", "mcp__notion__notion_describe"] } }

操作菜单（46 项操作，另有两个别名）

常见问题

免费版 Notion 套餐能用吗？ 可以。工作区所有者可在任何套餐中创建 Personal Access Token，服务端不需要其他配置。

有没有不使用 OAuth 的 Notion MCP 服务？ 就是这个。它使用令牌进行身份验证，因此无需任何人点击授权。Notion 托管的 MCP 仅在 Business 和 Enterprise 套餐中跳过 OAuth，且需要由工作区所有者创建 MCP 令牌。

它适用于哪些客户端？ 任何 MCP 客户端：Claude Code、Claude Desktop、Cursor、VS Code（Copilot 代理模式）、Codex、Gemini CLI、Cline、Windsurf、Zed、Continue，以及通过任何 MCP 主机连接的本地模型。更多信息请参阅常见问题。

故障排除

• 每次调用都显示“Notion auth failed”： 令牌缺失、已撤销或已过期。检查客户端配置中的 NOTION_TOKEN，然后确认令牌在 app.notion.com/developers/tokens 仍然有效。使用 add-mcp 安装时没有添加 --env？请使用该标志重新运行。
• object_not_found / “Could not find …”： 内部集成只能看到已连接到它的页面。连接该页面，或改用 PAT。
• “No parent page configured”： 在调用中传入 parent，或设置 NOTION_PAGE_ID。
• multi_source_database： 该数据库包含多个数据源。调用 list_data_sources，然后传入 data_source_id，而不是 database_id。
• 成功的结果中带有 warnings： 调用已执行。每条警告都会指出被忽略的字段或已更正的属性名称。
• Claude Desktop 中未显示工具： 令牌可能有拼写错误（必须保留在引号内），或者重新打开应用前没有完全退出（Cmd+Q）。
• 启动日志显示“Notion auth check failed”，但工具可用： 启动检查尽力而为；如果调用成功，可以忽略此提示。
• Docker 立即退出或显示“NOTION_TOKEN is not set”： 添加 -i，并使用 -e NOTION_TOKEN 或 -e NOTION_TOKEN=ntn_xxx，而不是 -e NOTION_TOKEN ntn_xxx。

仍无法解决？请查看常见问题或提交 GitHub issue。

隐私

服务运行在你的设备或自有主机上，并且只会通过 HTTPS 与 api.notion.com 通信，使用你配置的令牌（或在设置 HTTPS_PROXY 时通过你的代理通信）。没有遥测、没有分析，也没有我们的服务器参与其中。令牌会保留在 MCP 客户端存放令牌的位置。get_image 仅会获取 Notion 为其托管文件返回的签名 URL。upload_file 仅在收到请求时读取本地文件或获取 URL，并会拒绝解析到私有地址或环回地址的 URL。Notion 对你数据的处理受 Notion 隐私政策约束。

开发

git clone https://github.com/awkoy/notion-mcp-server.git && cd notion-mcp-server
npm install && npm run build && npm test

有关架构、在客户端中运行本地构建，以及针对真实工作区进行端到端测试的信息，请参阅：docs/development.md。欢迎提交 PR；提交前请运行 npm test。

License

MIT — see LICENSE.

mcp-name: io.github.awkoy/notion-mcp-server