Better Notion MCP Server

社区

面向 AI 代理的 Markdown 优先 Notion 服务器：页面、数据库、块与评论一次调用完成

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

63FMRS · C

一个功能覆盖面广、设计成熟的第三方 Notion MCP 服务器：Markdown 双向转换、8 个复合工具 39 个操作、自动分页与批量操作、stdio 与 OAuth 2.1 HTTP 双模式、npm 与 Docker 双分发、可部署到 Cloudflare，且有清晰的对比表与安全说明。适合希望在 AI 代理中高效操作 Notion 的用户，但需接受其为社区维护项目并妥善保管集成令牌。

最强项 · 文档质量 15/20 最弱项 · 可靠性 8/20

可靠性

8/20

安全与权限

12/20

维护活跃度

15/20

文档质量

15/20

安装易用性

13/20

查看各项评分依据

可靠性 8/20: README 展示了 CI 和 codecov 徽章,并声明「架构已稳定」,但本次静态审查仅能看到 README 与 server.json,未看到实际的 CI workflow 文件或测试代码,因此无法验证声明的可复现性。Status 一节还坦承此前存在「多进程竞争、浏览器标签页泛滥、安装体验不一致」的历史问题,说明可靠性并非一贯稳定。按静态审查上限规则(无可验证的 CI/测试证据不得超过 12 分),给予中低分。
安全与权限 12/20: NOTION_TOKEN 标记为必需且敏感,stdio 模式下以 AES-GCM 加密并绑定机器密钥存储于本地配置目录,HTTP 模式采用 OAuth 2.1 + PKCE、限流、会话绑定,凭证边界描述较为清晰,未见明文令牌或恶意代码痕迹,不触发红线。但存在扣分项:工具集中包含 archive/restore、delete_page、blocks delete 等不可逆操作,文档未说明是否有二次确认机制;README 的「Install with AI agent」建议智能体主动抓取并执行一个外部 URL 中的安装步骤,这是一种未经审查的远程指令注入模式,存在潜在风险;Cloudflare 自托管方案要求管理多个密钥但审计信息有限。综合给予中等偏上分数。
维护活跃度 15/20: 项目采用 semantic-release 与 Renovate 自动化依赖更新,版本号已到 2.40.1 显示发布节奏较快,同时发布 npm 包与 Docker 镜像,MIT 许可证明确,仓库未被归档,35 星、16 个未关闭 issue 说明有一定用户反馈但也有待处理事项。扣分点:未见独立的 SECURITY.md 或明确的安全响应渠道说明;作者同时维护约 19 个「姊妹项目」,存在单一维护者精力分散、长期治理能力存疑的风险。
文档质量 15/20: 文档结构非常完整,包含目录、安装、CLI、远程 HTTP、Smithery、工具与资源表、配置变量表、自托管与 Cloudflare 部署、竞品对比、安全说明与信任模型分级,覆盖面广且有具体示例。扣分点:大量细节(每客户端安装步骤、多用户配置等)依赖外部文档站点 mcp.n24q02m.com,静态审查无法核实其内容是否与源码一致;「paste this to your AI agent」的安装方式引导智能体读取并执行外部页面指令,不是标准可审查的文档实践。
安装易用性 13/20: 基础 stdio 安装非常简单:一段 JSON 配置 + npx 命令 + 一个环境变量即可,Docker 运行示例同样清晰。但静态审查规则限定在缺乏可验证执行证据时上限为 15 分。远程 HTTP/多用户/Cloudflare 自托管路径步骤较多(创建 OAuth App、KV 命名空间、多个 secret、wrangler 部署),复杂度明显上升;同时要求 Node.js >= 24 这一较新版本,可能存在平台兼容性门槛。

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

查看 FMRS 评分方法 →

选型与风险

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

适合谁

重度使用 Notion 且希望以 Markdown 方式与 AI 代理协作的用户
需要在 Claude Code、Cursor 等客户端中集成 Notion 工作流的开发者
需要文件上传、评论、块级编辑等完整 Notion 能力的自动化场景

不适合谁

寻求 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 会把所有用户合并为单一令牌桶，属严重风险
早前版本在凭证处理与守护进程自动派生上存在不稳定问题，应使用最新版本

安装接入

准备工作

运行环境：Node.js 24+ · Docker

NOTION_TOKEN 必填密钥 Notion 集成令牌，在 https://www.notion.so/my-integrations 创建，以 ntn_ 开头；stdio 模式必填。

NOTION_OAUTH_CLIENT_SECRET 可选密钥 Notion Public Integration 的 client secret，HTTP 模式必填。

CREDENTIAL_SECRET 可选密钥 Cloudflare 部署时必需，用于派生 OAuth 签名密钥以持久化用户身份。

其他可选配置项（7 个）

TRANSPORT_MODE 可选设为 http 切换到远程 HTTP 模式，可选。

MCP_TRANSPORT 可选作用同 TRANSPORT_MODE，设为 http 启用 HTTP 传输，可选。

PUBLIC_URL 可选自托管 HTTP 模式下服务器的公开 URL，用于 OAuth 重定向链接。

NOTION_OAUTH_CLIENT_ID 可选 Notion Public Integration 的 client ID，HTTP 模式必填。

MCP_AUTH_DISABLE 可选设为 1 可跳过 Bearer JWT 校验（仅限外部网关已做认证的场景）。

PORT 可选 HTTP 模式监听端口，默认由系统分配。

HOST 可选 HTTP 模式的绑定地址。

在 https://www.notion.so/my-integrations 创建集成并获取以 ntn_ 开头的令牌。
需要 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 授权页面。

.mcp.json

{"mcpServers":{"better-notion-mcp":{"command":"npx","args":["--yes","@n24q02m/better-notion-mcp@latest"],"env":{"NOTION_TOKEN":"ntn_your_token_here"}}}}

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

.vscode/mcp.json

{
  "servers": {
    "better-notion-mcp": {
      "command": "npx",
      "args": [
        "--yes",
        "@n24q02m/better-notion-mcp@latest"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_your_token_here"
      }
    }
  }
}

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

Terminal

claude mcp add better-notion-mcp -e NOTION_TOKEN=ntn_your_token_here -- npx --yes @n24q02m/better-notion-mcp@latest

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

生成并校验客户端配置

验证是否装好

启动后在 MCP 客户端的工具列表中应出现 pages、databases、blocks 等复合工具；调用 help 工具或用 users 工具的 me 操作能返回 Notion 用户信息即证明连接成功。

常见排障

确认 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 文档，多数旧变通方案已不再需要

试试这样问

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

在我的 Notion 工作区创建一个名为"项目计划"的页面，内容用 Markdown 写。
查询我的任务数据库中所有未完成的条目。
把指定页面的内容转成 Markdown 返回给我。
在某个页面下追加一个待办事项块并创建一条评论。

工具能力 11

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）

展开其余 3 个工具

config 只读

查看和管理凭证状态与配置生命周期

config__open_relay 只读

在浏览器中打开中继配置表单并返回中继 URL 与凭证状态

help 只读

获取任意复合工具的完整文档（通过 tool_name 参数）

使用场景

用自然语言或 Markdown 批量创建和整理 Notion 页面与数据库

在 AI 编程代理（如 Claude Code、Cursor）中直接查询和更新 Notion 内容

自动化评论管理与文件上传

自托管多用户远程 Notion 网关（OAuth 2.1）

支持客户端

Claude Code

Cursor

Codex

Gemini CLI

Windsurf

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

详细介绍

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。