适合谁
- 需要无头/令牌认证的自动化与 CI 场景（Notion 官方托管 MCP 仅支持 OAuth）
- 关注上下文/令牌成本的智能体（连接时仅 422 tokens 的工具模式）
- 需要批量变更、幂等性、自动重试与速率限制的工作流
- 自托管部署和自托管 HTTP 端点的开发者
- 使用任何支持 MCP 的客户端（Claude、Cursor、VS Code、Cline、Zed、Continue 等）的用户
N
61FMRS · C
一个面向智能体设计、文档详尽的第三方 Notion MCP 服务器。两工具 + 43 操作、按需加载模式、批量/幂等/重试、访问控制与 HTTP 传输等工程细节扎实，尤其适合无人值守和令牌成本敏感的场景。需要注意它是社区项目而非 Notion 官方，使用即需信任其代码或自行审计；HTTP 模式须配置鉴权。
这是一个由第三方（awkoy）维护的 Notion Model Context Protocol 服务器，并非 Notion 官方出品。它通过令牌认证（个人访问令牌 PAT 或内部集成密钥）运行，可在 CI、定时任务、后台智能体等无人值守场景使用。服务器只暴露两个 MCP 工具（notion_execute 和 notion_describe），通过按需加载的操作模式调度 43 项操作，覆盖页面、块、数据库、数据源、视图、评论、用户和文件。支持批量变更（原子回滚）、幂等键、速率限制自动重试、Markdown 双向转换、Notion 模板、文件上传、扁平化查询结果，以及通过 NOTION_READ_ONLY 和操作允许/阻止列表进行访问控制。除 stdio 外还支持 Streamable HTTP 远程传输（单租户，可用 MCP_AUTH_TOKEN 保护）。
工具能力
notion_execute
执行任一操作（共 43 项，含批量模式），负载校验失败时返回模式、示例和修复提示，帮助模型一轮内自我纠正。
notion_describe
返回某个操作的 JSON Schema 和可运行示例，适用于复杂调用前的查询。
安装接入
- 在 app.notion.com/developers/tokens 创建个人访问令牌（ntn_…，推荐）或创建内部集成密钥；2. 运行
claude mcp add notion -s user -e NOTION_TOKEN=ntn_… -- npx -y notion-mcp-server（Claude Code），或在 Claude Desktop / Cursor 的 mcpServers 配置中添加 command: npx、args: ["-y","notion-mcp-server"]、env: {"NOTION_TOKEN": "…"}；3. Claude Desktop 也可下载 .mcpb 扩展一键安装；4. Docker 运行：docker run --rm -i -e NOTION_TOKEN ghcr.io/awkoy/notion-mcp-server:latest（stdio 需 -i 标志）；5. 远程模式：设置 MCP_TRANSPORT=http 启动，外部暴露时务必设置 MCP_AUTH_TOKEN。
claude_desktop_config.json
{"mcpServers":{"notion":{"command":"npx","args":["-y","notion-mcp-server"],"env":{"NOTION_TOKEN":"ntn_paste_your_token_here"}}}}
选型与风险
不适合谁
- 想在 claude.ai / ChatGPT 网页界面中一键连接 Notion 的用户（应使用 Notion 官方托管 MCP，其内置连接器要求 OAuth 托管服务器）
- 偏好每个端点一个工具的官方开源服务器体验的用户
- 不愿将 Notion 令牌交给第三方开源服务的团队（虽可自行审计源码或自建）
所需权限
- 需要 NOTION_TOKEN：Notion 个人访问令牌（ntn_…，推荐，权限等同于本人账户，约 1 年过期）或内部集成密钥（仅限显式 Connect 的页面）
- 可选 NOTION_PAGE_ID 作为 create_page / create_database 的默认父页面
- 可选 NOTION_UPLOAD_ROOT 限制 upload_file 可读取的本地目录
- 可选 NOTION_READ_ONLY=true 或 NOTION_ALLOWED_OPERATIONS=read 实现只读部署；NOTION_ALLOWED_OPERATIONS / NOTION_BLOCKED_OPERATIONS 可按操作或分组预设控制权限
风险与副作用
- 令牌权限等同于持有者账户：PEN 令牌可访问你能看到的全部页面，泄露即等于账户内容泄露，应按成员分开发放并在设备丢失时立即吊销
- 外部绑定 HTTP 端点时，能访问 /mcp 的人即以你的 NOTION_TOKEN 行事；未设置 MCP_AUTH_TOKEN 会有严重暴露风险
- upload_file 的 path 来源若不加 NOTION_UPLOAD_ROOT 限制，可读取服务器进程可访问的任意文件
- 多数写入操作可修改或删除内容：blocking destructive 并不覆盖 update_database 的 in_trash 等参数，保证不可变更需用 READ_ONLY 或 allow=read
- HTTP 模式为单租户，所有请求共用一个令牌，不适合多用户共享
常见排障
- object_not_found：内部集成令牌未连接到页面——改用 PAT 或在页面执行 Connect
- 所有调用报 Notion auth failed：令牌缺失、被吊销或已过期（PAT 一年过期），检查客户端配置中的 NOTION_TOKEN
- No parent page configured：调用时传入 parent 或设置 NOTION_PAGE_ID
- query_database 返回 multi_source_database：改用 list_data_sources 后传 data_source_id
- Claude Desktop 看不到工具：令牌引号内拼写错误，或未完全退出应用（Cmd+Q）后重启
- Docker 立即退出：stdio 需要加 -i 标志；NOTION_TOKEN 未传入时用 -e NOTION_TOKEN（转发）或 -e NOTION_TOKEN=ntn_xxx
使用场景
在 Claude Desktop / Cursor 中用自然语言创建页面、查询数据库、追加块
批量重命名 50 个页面（单次批量调用，10 路并发、幂等重试）
从 Notion 模板创建页面并填充内容
全 Markdown 往返编辑（get_page_markdown → 修改 → update_page_markdown）
在 CI / 定时任务 / 后台智能体中无头读写 Notion
按视图的筛选/排序查询数据库并返回扁平化行
上传单个或多分片文件到页面
支持客户端
Claude Code完整支持
Claude Desktop完整支持
Cursor完整支持
VS Code (Copilot agent mode)完整支持
Cline完整支持
Zed完整支持
Continue完整支持
ChatGPT部分支持