Notion MCP Server

社区

用一个令牌将 Claude、Cursor 等智能体接入 Notion 的无头 MCP 服务器

分类: 团队协作第 8 / 55
Stars: ★ 177 热门
传输方式: stdio（本地进程） · Streamable HTTP
运行环境: Node.js · Docker
凭据: 需要 API Key / 凭据
许可证: MIT
最近提交: 4 天前
工具数: 2

61FMRS · C

一个面向智能体设计、文档详尽的第三方 Notion MCP 服务器。两工具 + 43 操作、按需加载模式、批量/幂等/重试、访问控制与 HTTP 传输等工程细节扎实，尤其适合无人值守和令牌成本敏感的场景。需要注意它是社区项目而非 Notion 官方，使用即需信任其代码或自行审计；HTTP 模式须配置鉴权。

最强项 · 文档质量 17/20 最弱项 · 可靠性 9/20

可靠性

9/20

安全与权限

11/20

维护活跃度

11/20

文档质量

17/20

安装易用性

13/20

查看各项评分依据

可靠性 9/20: README 详细描述了双工具（notion_execute/notion_describe）分发 43 个操作、批处理、幂等、限速重试等机制，并声称有 vitest 测试套件覆盖 markdown 解析、分发器、批处理语义、访问控制和 HTTP 传输等关键路径。但本次审查未看到实际的测试文件或 CI 工作流文件，所有这些说法仅来自 README 的文字描述，无法在静态层面得到验证；manifest 与 README 中对传输方式（stdio）、包名、环境变量描述基本一致，未发现明显矛盾。按静态校准规则，在没有可验证的 CI/测试证据前，可靠性不得高于 12 分，因证据缺失带来的不确定性，最终给到中低分。
安全与权限 11/20: 凭证通过环境变量 NOTION_TOKEN 传递并在 manifest 中标记为 isSecret，做法regular；文档清楚披露 PAT 的权限范围等同用户本人全部可见内容，并提供作用域更小的 Internal Integration 方案作为替代，体现了良好的透明度。提供 NOTION_READ_ONLY、NOTION_ALLOWED_OPERATIONS/BLOCKED_OPERATIONS 实现最小权限配置，HTTP 远程模式默认绑定 127.0.0.1，非回环地址会警告需要 MCP_AUTH_TOKEN。但默认配置下写操作和破坏性操作（archive_page/trash_page、delete_block、delete_comment 等）均默认启用，没有默认的二次确认机制；同时文档自己承认 update_database/update_data_source 的 in_trash 参数、update_page_markdown 替换正文等‘破坏性等价’操作不受 destructive 黑名单约束，此为已知但未完全缓解的权限缺口。NOTION_UPLOAD_ROOT 默认未设置时文件路径读取范围不受限，同样是文档披露但默认不开启防护的风险点。综合看，主要风险已被清楚披露且有较完善的可选缓解手段，但默认状态下的权限收紧与确认机制不完整，故未能给到高分。
维护活跃度 11/20: 仓库采用 MIT 许可证，星标 165，未归档，未平仓 issue 12 个，版本号已到 3.0.0 并提供 MIGRATION.md 说明从 v1.x 升级路径，显示出一定的持续演进痕迹。但所提供材料中没有具体的提交历史、发布节奏、issue 响应时间或安全响应渠道（如 SECURITY.md）的证据，无法确认维护活跃度与治理规范的完整性，这部分缺失按规则应作扣分处理，而非假设为最佳情况。
文档质量 17/20: README 内容非常详尽，涵盖快速开始（多客户端配置示例）、认证方式对比（PAT vs Internal Integration）、环境变量完整表格、操作限制配置、远程/HTTP 传输的安全提示、故障排查、FAQ 以及面向非开发者的完整分步教程，且主动披露了若干已知限制（如破坏性黑名单的覆盖盲区、上传路径风险）。这已经接近“分层文档、充分示例并披露局限性”的高分标准。扣分点在于文档中引用的对比数据（如“422 tokens”“17163 tokens”的具体数字）来自未随材料提供、无法验证的 benchmark 链接，且存在较多对比竞品的营销性措辞，需谨慎对待其准确性。
安装易用性 13/20: 文档给出了 npx、Docker/Podman、Claude Desktop 一键扩展（.mcpb）、VS Code 一键安装徽章等多种安装路径，步骤描述清晰、覆盖主流客户端，属于典型的 npm 包型 MCP Server 安装方式，理论上摩擦较低。但按静态校准要求，在没有见到实际 CI 工作流文件和已提交测试作为可验证执行证据的情况下，安装易用性分数不得超过 15 分，因此即便步骤描述清楚，也需保持在此上限之下并因证据不足适度扣分。

静态评测 · 未实际运行收录于 2026-09-07

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络修改第三方账户数据

适合谁

需要无头/令牌认证的自动化与 CI 场景（Notion 官方托管 MCP 仅支持 OAuth）
关注上下文/令牌成本的智能体（连接时仅 422 tokens 的工具模式）
需要批量变更、幂等性、自动重试与速率限制的工作流
自托管部署和自托管 HTTP 端点的开发者
使用任何支持 MCP 的客户端（Claude、Cursor、VS Code、Cline、Zed、Continue 等）的用户

不适合谁

想在 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 模式为单租户，所有请求共用一个令牌，不适合多用户共享

安装接入

准备工作

运行环境：Node.js · Docker

NOTION_TOKEN 必填密钥 Notion 个人访问令牌（ntn_...）或内部集成密钥，在 app.notion.com/developers/tokens 创建，必填。

MCP_AUTH_TOKEN 可选密钥 HTTP 模式的 Bearer 认证令牌，设置后所有 /mcp 请求需携带。

其他可选配置项（11 个）

NOTION_PAGE_ID 可选可选的默认父页面 ID，create_page/create_database 未传 parent 时使用。

NOTION_RATE_LIMIT 可选限流器每秒请求数，默认 3。

NOTION_READ_ONLY 可选设为 true/1/yes 可一键禁用所有写操作。

NOTION_ALLOWED_OPERATIONS 可选逗号分隔的操作或分组白名单，如 read。

NOTION_BLOCKED_OPERATIONS 可选逗号分隔的黑名单，优先于白名单。

NOTION_UPLOAD_ROOT 可选限制 upload_file 的 path 来源目录，防止模型读取任意文件。

HTTPS_PROXY 可选 HTTP(S) 代理地址，用于企业网络访问 Notion API。

HTTP_PROXY 可选 HTTP 代理地址，小写形式也接受。

MCP_TRANSPORT 可选设为 http 启用 Streamable HTTP 传输，默认 stdio。

PORT 可选 HTTP 模式监听端口，默认 3000。

HOST 可选 HTTP 模式绑定地址，默认 127.0.0.1；设 0.0.0.0 时必须配合 MCP_AUTH_TOKEN。

在 app.notion.com/developers/tokens 创建个人访问令牌（ntn_…，推荐）或创建内部集成密钥
运行 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": "…"}
Claude Desktop 也可下载 .mcpb 扩展一键安装
Docker 运行：docker run --rm -i -e NOTION_TOKEN ghcr.io/awkoy/notion-mcp-server:latest（stdio 需 -i 标志）
远程模式：设置 MCP_TRANSPORT=http 启动，外部暴露时务必设置 MCP_AUTH_TOKEN。

.mcp.json

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

以 Claude Code 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

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

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

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

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

重启客户端后，在新对话中输入 /，应能看到 notion_execute 和 notion_describe 两个工具；然后让 AI 用 Notion 创建一个测试页面，收到页面链接即说明连接成功。

常见排障

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

试试这样问

连接成功后，可以直接对 AI 助手这样说：

用 Notion 创建一个名为'Hello from my agent'的页面，并添加一个包含三件事的待办清单。
在我的 Tasks 数据库里找出所有 Status 为 Doing 的行，并告诉我哪些已逾期。
把昨天会议纪要页面的标题改成'Q3 计划'。
在昨天会议纪要页面下发表一条一段话的总结评论。

工具能力 2

notion_execute 写入

执行任一操作（共 43 项，含批量模式），负载校验失败时返回模式、示例和修复提示，帮助模型一轮内自我纠正。

notion_describe 只读

返回某个操作的 JSON Schema 和可运行示例，适用于复杂调用前的查询。

使用场景

在 Claude Desktop / Cursor 中用自然语言创建页面、查询数据库、追加块

批量重命名 50 个页面（单次批量调用，10 路并发、幂等重试）

从 Notion 模板创建页面并填充内容

全 Markdown 往返编辑（get_page_markdown → 修改 → update_page_markdown）

在 CI / 定时任务 / 后台智能体中无头读写 Notion

按视图的筛选/排序查询数据库并返回扁平化行

上传单个或多分片文件到页面

支持客户端

Claude Code

Claude Desktop

Cursor

VS Code

Cline

Zed

Continue

ChatGPT部分支持

依据项目文档列出，未经本站实测。

详细介绍

这是一个由第三方（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 保护）。