Notion MCP Server

官方

Notion 官方 MCP 服务器,支持通过 AI 代理查询、编辑 Notion 页面与数据库。

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

64FMRS · C

该项目是 Notion 官方维护的开源本地 MCP 服务器,功能覆盖页面、数据库(数据源)、评论及 Markdown 页面编辑,文档详尽且随 API 更新持续演进(如 v2.0.0 的数据源迁移)。但官方已明确表示优先支持全新的远程托管版 Notion MCP,并暗示该本地仓库未来可能被弃用、Issue 与 PR 不再被积极处理,评估长期使用时需考虑这一点。

最强项 · 安全与权限 17/20 最弱项 · 可靠性 8/20

可靠性

8/20

安全与权限

17/20

维护活跃度

10/20

文档质量

16/20

安装易用性

13/20

查看各项评分依据

可靠性 8/20: README 描述了工具集从 19 个变为 22 个、API 版本迁移（2025-09-03 到 2026-03-11）等具体细节，且提到 `npm run build` / `npm test` 命令，显示代码库存在构建与测试脚本，但本次审查未看到任何 CI workflow 文件或实际测试用例内容，无法验证 MCP 初始化/工具列表握手在真实环境下可复现。按静态校准规则，缺乏可验证的执行证据（CI + 已提交测试覆盖关键路径），reliability 不得超过 12。故给出中低分。
安全与权限 17/20: 该服务器展现出较强的安全意识：建议用户在 Notion 集成中配置最小权限（只读能力）、明确声明通过 MCP 无法删除数据库；HTTP 传输默认要求 bearer token 鉴权，禁用鉴权需要显式的 `--unsafe-disable-auth` 危险标志并附带警告；即使禁用鉴权也启用了 DNS rebinding 防护（校验 Host/Origin）；多租户 token passthrough 功能对 token 前缀做校验、按 session 隔离、日志脱敏，并建议全程使用 TLS。未发现凭证明文示例（均为占位符 `ntn_****`），无未经确认的不可逆危险默认操作，不触发红线。扣分点在于：默认场景下用户可能未主动收窄集成权限（只读为可选而非默认），且缺少对 Notion API 侧数据留存/加密的说明，故未给满分。
维护活跃度 10/20: 仓库为 Notion 官方组织下项目，MIT 许可证，README 显示近期有实质性版本更新（v2.0.0 API 迁移、新增 Markdown 工具并适配 2026-03-11 版本 API），说明代码层面仍在积极演进。但 README 顶部明确声明：本地服务器可能被弃用，'Issues and pull requests here are not actively monitored'，即官方已明确降低对本仓库社区支持的投入，且未来可能整体弃用。这是明确的治理/支持信号弱化，需要显著扣分，故评级为'活跃但治理存在明显缺口'区间的中等偏下水平。
文档质量 16/20: README 内容详尽，覆盖多客户端安装（Cursor、Claude Desktop、Zed、Copilot CLI）、npm 与 Docker 两种运行方式、STDIO 与 HTTP 两种传输模式、鉴权配置的三种方案、token passthrough 的详细语义及使用示例、版本迁移对照表等，证据可复核。不足之处：未逐一列出全部 22 个工具的参数与限制、未设置专门的故障排查(troubleshooting)章节、未披露速率限制或调用成本信息，因此未达满分。
安装易用性 13/20: 安装路径清晰，提供了 npm/npx 与 Docker（官方镜像及本地构建）两类方式，以及多个主流客户端的配置示例，步骤明确且给出了截图式指引。但仍需要用户手动创建 Notion 集成、逐页/逐库授权连接、正确配置环境变量或 headers，属于'可用但仍需手动、存在一定脆弱性'的安装体验。根据静态校准规则，在没有可验证执行证据的情况下 setup 不得超过 15 分，故给出该区间内的中等分数。

静态评测 · 未实际运行收录于 2026-08-26

查看 FMRS 评分方法 →

选型与风险

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

适合谁

已经在 Notion 中管理文档/知识库,希望通过 AI 客户端(Claude Desktop、Cursor 等)直接操作 Notion 内容的团队或个人
需要自建/自托管本地 MCP 服务器,而非使用远程托管方案的开发者
需要脚本化或代理化处理 Notion 数据库记录的自动化工作流

不适合谁

希望使用标准 OAuth 免配置安装、且需要官方持续积极支持的用户(应使用 Notion 官方新推出的远程 Notion MCP)
不希望将 Notion 集成令牌交给本地运行的 LLM 客户端的用户
需要执行本集成未开放能力(如删除数据库)的场景

所需权限

一个 Notion 内部集成令牌(NOTION_TOKEN 或 OPENAPI_MCP_HEADERS 中的 Authorization),其权限范围由集成的 Capabilities 配置决定(可限制为只读)
仅限于显式连接到该集成的页面和数据库,而非整个工作区
使用 HTTP 传输时需要额外的 Bearer 鉴权令牌(--auth-token / AUTH_TOKEN)
网络访问 Notion API 的权限

风险与副作用

若集成被授予较广的读取/写入能力且连接了大量页面,相当于把这些工作区内容暴露给 LLM,存在数据泄露或误操作风险
使用 --unsafe-disable-auth 关闭 HTTP 鉴权后,服务器可能被通过 DNS 重绑定从访问者浏览器打开的网页间接访问,仅应在隔离网络中使用
开启多租户令牌透传(token passthrough)时,若未正确部署 TLS 及网关鉴权,存在 Notion 令牌被截获或错发给其他客户端的风险
README 明确提示该本地仓库未来可能被弃用,Issue/PR 不再被积极处理,长期维护和安全更新没有保证
如果将 NOTION_TOKEN 或 OPENAPI_MCP_HEADERS 直接写入共享的客户端配置文件,存在密钥泄露风险

安装接入

准备工作

运行环境：Node.js · Docker

NOTION_TOKEN 必填密钥 Notion 内部集成的密钥（ntn_ 开头），在 notion.so/profile/integrations 的 Configuration 页获取。

OPENAPI_MCP_HEADERS 可选密钥高级用法：包含 Authorization 和 Notion-Version 的 JSON 头字符串，用于替代 NOTION_TOKEN。

AUTH_TOKEN 可选密钥 Streamable HTTP 传输模式下的服务器自身 bearer 认证令牌，可自行指定。

其他可选配置项（1 个）

ENABLE_TOKEN_PASSTHROUGH 可选设为 true 时启用逐请求的 Notion 令牌透传（多集成部署），非密钥。

在 Notion 的“我的集成”页面创建一个内部集成(Integration),并获取以 ntn_ 开头的令牌;可在“Configuration”中限制其能力(如仅“读取内容”)以降低风险。
在需要开放给该集成的页面/数据库中,通过“Access”标签或页面右上角“Connect to integration”将其连接。
在客户端(如 Claude Desktop、Cursor、Zed、GitHub Copilot CLI)的 MCP 配置文件中添加通过 npx 或 Docker 启动的服务器条目,并设置 NOTION_TOKEN(或 OPENAPI_MCP_HEADERS)环境变量。
如需通过 HTTP 而非默认的 stdio 访问,可加 --transport http 并配置 --auth-token 或 AUTH_TOKEN 用于鉴权;多租户场景可启用 --enable-token-passthrough,让每个客户端在连接时通过 Notion-Token 请求头传入各自的 Notion 令牌。

claude_desktop_config.json

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

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

.vscode/mcp.json

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

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

Terminal

claude mcp add notionApi -e 'NOTION_TOKEN=ntn_****' -- npx -y @notionhq/notion-mcp-server

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

生成并校验客户端配置

验证是否装好

在客户端工具列表中确认出现 query-data-source 和 retrieve-page-markdown 等工具；然后输入"获取页面 <page_id> 的内容"，能返回 Notion 页面内容即证明连接成功。

常见排障

确认 Notion 集成已被连接到目标页面/数据库(通过 Access 标签或页面的 Connect to integration)
确认集成的 Capabilities 权限(如是否开启写入)满足所调用工具的需求
检查客户端配置中 NOTION_TOKEN 或 OPENAPI_MCP_HEADERS 是否正确设置且未过期
升级到 v2.0.0 后,若脚本/提示词硬编码了旧的数据库工具名或 database_id 参数,需改为对应的数据源工具及 data_source_id
使用 Markdown 相关工具(retrieve-page-markdown / update-page-markdown)报错时,确认所用的 Notion-Version 请求头(默认由服务器针对该操作设为 2026-03-11)未被 OPENAPI_MCP_HEADERS 中的自定义值覆盖
使用 Streamable HTTP 传输时,确认请求头中的 Bearer 令牌与服务器的 --auth-token/AUTH_TOKEN 一致

试试这样问

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

在"Getting started"页面上评论"Hello MCP"
把标题为"Notion MCP"的页面添加到"Development"页面下
获取页面 1a6b35e6e67f802fa7e1d27686f017f2 的内容
查询某个数据源中所有状态为待办的条目

工具能力 9

query-data-source 只读

使用过滤条件和排序查询某个数据源(数据库)。

retrieve-a-data-source 只读

获取某个数据源的元数据与结构(schema)。

update-a-data-source 写入

更新数据源的属性/结构。

create-a-data-source 写入

在数据库下创建新的数据源。

list-data-source-templates 只读

列出某个数据源中可用的页面模板。

move-page 写入

将页面移动到另一个父页面或数据库下。

retrieve-a-database 只读

获取数据库的元数据,包括其包含的数据源 ID 列表。

retrieve-page-markdown 只读

以 Markdown 格式读取页面的完整内容,可选择内联会议纪要转录文本。

展开其余 1 个工具

update-page-markdown 写入

使用 Markdown 编辑页面内容,可整页替换,也可做定向查找替换。

使用场景

让 AI 助手搜索、读取和编辑 Notion 页面内容

让 AI 代理在 Notion 数据库(数据源)中查询、筛选、更新记录

为页面添加评论或创建新的子页面

以 Markdown 方式批量读写页面全文,降低 AI 交互的 token 开销

支持客户端

Claude Desktop

Cursor

Zed

GitHub Copilot CLI

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

详细介绍

本仓库是 Notion 官方维护的本地 MCP 服务器,基于 Notion API 实现,通过标准输入输出(stdio)或可流式传输的 HTTP 与 AI 客户端通信。它提供搜索、页面创建与评论、数据库(数据源)查询与更新等工具,并新增了以 Markdown 形式读写整页内容的工具(需要 Notion API 版本 2026-03-11),相比原始 block JSON 更省 token。README 中明确说明 Notion 已推出全新的远程托管版 “Notion MCP”(支持标准 OAuth 安装),并优先支持该远程版本;本地版本未来可能被弃用,Issue 和 PR 也不会被积极处理。v2.0.0 版本迁移到 Notion API 2025-09-03,用“数据源(data source)”概念取代原来的数据库操作工具,并将参数由 database_id 改为 data_source_id。