适合谁
- 重度使用 Notion 且希望以 Markdown 方式与 AI 代理协作的用户
- 需要在 Claude Code、Cursor 等客户端中集成 Notion 工作流的开发者
- 需要文件上传、评论、块级编辑等完整 Notion 能力的自动化场景
B
63FMRS · C
一个功能覆盖面广、设计成熟的第三方 Notion MCP 服务器：Markdown 双向转换、8 个复合工具 39 个操作、自动分页与批量操作、stdio 与 OAuth 2.1 HTTP 双模式、npm 与 Docker 双分发、可部署到 Cloudflare，且有清晰的对比表与安全说明。适合希望在 AI 代理中高效操作 Notion 的用户，但需接受其为社区维护项目并妥善保管集成令牌。
Better Notion MCP 是一个开源（MIT）的模型上下文协议（MCP）服务器，由 n24q02m 维护，并非 Notion 官方产品。它以 Markdown 作为输入输出格式封装 Notion API，提供 8 个复合工具（39 个操作）及 config、config__open_relay、help 三个基础设施工具，支持自动分页与批量操作，宣称可减少约 77% 的 token 消耗。支持本地 stdio（集成令牌）与远程 HTTP（OAuth 2.1）双传输模式，可通过 npm 包或 Docker 镜像运行，也可自托管到 Cloudflare Workers。
工具能力
pages
创建、读取、更新和组织页面（create/get/get_property/update/move/archive/restore/duplicate）
databases
数据库 CRUD 与数据库内页面管理、数据源操作及模板列表（10 个操作）
blocks
读取和操作块内容（get/children/append/update/delete）
users
列出和检索用户信息（list/get/me/from_workspace）
workspace
工作区元数据与跨工作区搜索（info/search）
comments
页面评论与讨论回复（list/get/create）
content_convert
在 Markdown 与 Notion 块之间双向转换
file_uploads
向 Notion 上传文件，支持单部分与多部分上传（create/send/complete/retrieve/list）
config
查看和管理凭证状态与配置生命周期
config__open_relay
在浏览器中打开中继配置表单并返回中继 URL 与凭证状态
help
获取任意复合工具的完整文档（通过 tool_name 参数）
安装接入
- 在 https://www.notion.so/my-integrations 创建集成并获取以 ntn_ 开头的令牌。2. 需要 Node.js >= 24，将 MCP 客户端配置为 command: npx，args: ["--yes","@n24q02m/better-notion-mcp@latest"]，并在 env 中设置 NOTION_TOKEN；或使用 Docker：docker run --rm -i -e NOTION_TOKEN=... n24q02m/better-notion-mcp:latest。远程 HTTP 模式可传 --http 并配置 OAuth 客户端 ID/密钥。HTTP 模式下首次连接会打开 Notion 的 OAuth 授权页面。
claude_desktop_config.json
{"mcpServers":{"better-notion-mcp":{"command":"npx","args":["--yes","@n24q02m/better-notion-mcp@latest"],"env":{"NOTION_TOKEN":"ntn_your_token_here"}}}}
选型与风险
不适合谁
- 寻求 Notion 官方支持服务器的用户（这是第三方开源项目）
- 不想授予 Notion 集成令牌或完成 OAuth 授权的用户
- Node.js 版本低于 24 且无法使用 Docker 的环境
所需权限
- 需要 Notion 集成令牌（ntn_ 开头），仅能访问被显式共享给该集成的页面
- HTTP 模式需要 Notion Public Integration 的 OAuth 客户端 ID 与密钥
- 令牌通过 NOTION_TOKEN 环境变量传入，属于机密信息
风险与副作用
- 第三方项目，非 Notion 官方维护，需自行评估代码
- stdio 模式下令牌以 AES-GCM 加密存储于本地配置文件，但集成令牌本身权限较大
- HTTP 模式令牌仅保存在进程内存中，重启即失效（托管模式）
- 在共享/公开部署上设置 MCP_AUTH_DISABLE=1 会把所有用户合并为单一令牌桶，属严重风险
- 早前版本在凭证处理与守护进程自动派生上存在不稳定问题，应使用最新版本
常见排障
- 确认 NOTION_TOKEN 已设置且以 ntn_ 开头，并在 Notion 中将目标页面共享给该集成
- 确认 Node.js 版本 >= 24（npx 方式）
- 远程模式需正确设置 TRANSPORT_MODE=http、PUBLIC_URL、NOTION_OAUTH_CLIENT_ID/SECRET
- HTTP 模式下 401/授权失败时检查 OAuth 重定向 URI 是否与 Notion Public Integration 配置一致
- 从旧版本升级后遇到问题，参考官方 setup 文档，多数旧变通方案已不再需要
使用场景
用自然语言或 Markdown 批量创建和整理 Notion 页面与数据库
在 AI 编程代理（如 Claude Code、Cursor）中直接查询和更新 Notion 内容
自动化评论管理与文件上传
自托管多用户远程 Notion 网关（OAuth 2.1）
支持客户端
Claude Code完整支持
Cursor完整支持
Codex完整支持
Gemini CLI完整支持
Windsurf完整支持
Smithery完整支持