better-notion-mcp

notion

mcp-name: io.github.n24q02m/better-notion-mcp

面向 AI Agent 的 Markdown 优先 Notion——一次调用即可处理页面、数据库、区块和评论。

来自 n24q02m 的姊妹项目（点击展开）

| 项目 | 标语 | 标签 | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | AI Agent 在共享文件夹中进行同伴聊天——无需人工转发，无需编排器， wor... | 工具 | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | 用于高效利用 token 进行代码审查的知识图谱——语义搜索和调用-... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | 支持 `.driveignore` 过滤的双向 Google Drive 同步——rclone 引擎，Windows 托盘 | 工具 | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | 为 AI Agent 提供 IMAP/SMTP 邮件功能——读取、发送、整理文件夹并管理附... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | 面向 Godot Engine 的组合式 MCP 服务——提供 17 个组合工具，支持 AI 辅助游戏开... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | 面向 AI Agent 的 Markdown 优先型 Notion——页面、数据库、区块和评论... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | 可直接替换 python-semantic-release 的分支，内置发布安全防护（孤... | 工具 | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | 为 AI Agent 提供 Telegram 功能——支持两种 bo... 上的消息、聊天、媒体和联系人 | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP 服务（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...） | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | n24q02m MCP 服务的 Claude Code 插件市场——安装网页搜索... | 市场 | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | 为 AI Agent 提供图像和视频理解与生成——支持 Gemini、Op... | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | 通过 batchexecute API 批量操作 Jules 任务的 Chrome 扩展——一... | 工具 | | [mcp-core](https://github.com/n24q02m/mcp-core) | 构建 MCP 服务的共享基础——Streamable HTTP 传输、OAuth... | MCP | | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | 支持混合搜索和嵌入式同步的持久化 AI 记忆。开放、免费、无限... | MCP | | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | 通过 ONNX Runtime 和 GGUF 实现的轻量级 Qwen3 文本嵌入与重排序 | 库 | | [skret](https://github.com/n24q02m/skret) | 无需服务器的密钥管理。 | 命令行 | | [tacet](https://github.com/n24q02m/tacet) | 一种自蒸馏神经符号级联架构，可在知识...之间分摊大模型成本 | 工具 | | [web-core](https://github.com/n24q02m/web-core) | 用于搜索、抓取、HTTP 安全和 st... 的共享 Web 基础设施包 | 库 | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | 面向 AI Agent 的开源 MCP 服务：网页搜索、内容提取和 lib... | MCP |

目录

• 功能
• 安装
• 命令行
• 远程（HTTP 模式）
• Smithery
• 状态
• 文档
• 工具
• 配置
• 比较
• 安全性
• 从源代码构建
• 信任模型
• 许可证

## 功能

• Markdown 输入，Markdown 输出 —— 使用人类可读内容，而不是原始 JSON 块
• 8 个复合工具，39 项操作 —— 一次调用即可完成，无需串联 2 个以上原子 Notion 端点（另有 config 和 help）
• 自动分页和批量操作 —— 无需手动处理游标或循环
• 分层令牌优化 —— 通过压缩描述和按需使用 help 工具，减少约 77%
• 双传输模式 —— 本地 stdio（集成令牌）或远程 HTTP（每位用户独享或共享 bearer token）

安装

使用 npx（Node.js >= 24）和 Notion 集成令牌运行，令牌可从 https://www.notion.so/my-integrations 获取（以 ntn_ 开头）：

// MCP client config (e.g. .mcp.json / Claude Code / Cursor)
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/notion@latest"],
      "env": { "NOTION_TOKEN": "ntn_your_token_here" }
    }
  }
}

软件包为 @n24q02m/notion（原名为 @n24q02m/better-notion-mcp； 旧软件包将在发布最后一个版本后停止更新）。MCP Registry ID 保持为 io.github.n24q02m/better-notion-mcp，旧的 better-notion-mcp 命令仍作为 notion 的别名保留。

或者运行已发布的 Docker 镜像（stdio）：

docker run --rm -i -e NOTION_TOKEN=ntn_your_token_here n24q02m/notion:latest

安装矩阵

客户端	安装
Claude Code	/plugin marketplace add n24q02m/claude-plugins + /plugin install better-notion-mcp@n24q02m-plugins（stdio；会提示输入 NOTION_TOKEN），或在 .mcp.json / 客户端设置中添加 mcpServers 条目
Codex CLI	在 ~/.codex/config.toml 中添加 [mcp_servers.notion] 块（stdio command/args 或 HTTP type/url）
OpenCode	在 opencode.json 中添加 mcpServers 块
Cursor / Windsurf / Gemini CLI / 任意 MCP 客户端	在客户端配置中添加 mcpServers JSON，格式与上述示例相同

各客户端的完整操作指南：mcp.n24q02m.com/servers/better-notion-mcp/setup/。 各客户端（Claude Code、Codex、Gemini CLI、Cursor、Windsurf）的设置方法和 HTTP 模式，请参阅文档部分。

CLI

安装软件包后会提供 notion 二进制文件（以及旧版 better-notion-mcp 别名；可通过 npx 或全局安装后运行）。不带参数时，它会启动 MCP 服务并通过 stdin/stdout 通信，因此通常由 MCP 客户端启动，而非手动运行。子命令：auth 用于保存 Notion 集成令牌；config、status、logout、doctor 和 token 来自共享的 hull CLI。

# Start the stdio server (default transport; requires NOTION_TOKEN)
NOTION_TOKEN=ntn_your_token_here npx --yes @n24q02m/notion@latest

# Start the remote HTTP server (bearer token) instead of stdio
npx --yes @n24q02m/notion@latest --http

参数 / 环境变量	效果
(none)	stdio 传输（默认）；需要 NOTION_TOKEN
--http	HTTP 传输；通过 MCP_AUTH_MODE 选择身份验证方式（默认为 multi，也可选 token 或 no-auth）

完整的环境变量参考，请参阅配置。

远程（HTTP 模式）

使用 HTTP 传输部署后，该服务会成为受 bearer token 身份验证保护的远程端点——服务配置中无需集成令牌。将支持远程 HTTP 服务的 MCP 客户端指向你部署该服务的主机：

// MCP client config -- remote HTTP (bearer token)
{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

在 multi 模式（默认）下，每位用户都会列在用户文件中（MCP_USERS_FILE，默认为 ~/.hull/users.toml），并拥有独立的令牌和凭据命名空间。在 token 模式下，所有客户端共用一个令牌，其 scrypt 哈希值由 MCP_AUTH_TOKEN_HASH 设置。有关如何搭建此类实例，请参阅自托管（远程模式）。

Smithery

仓库提供了用于 Smithery 的 smithery.yaml 配置。Smithery 通过 stdio 启动服务（npx -y @n24q02m/notion），无需在安装时进行配置——运行时通过 NOTION_TOKEN 或 config 工具提供 Notion 凭据（参阅配置）。

状态

2026-05-02——架构稳定化更新

过去几个月，凭据处理和守护进程桥接自动启动模式经历了重大变动，导致多进程竞争、浏览器标签页泛滥，以及各插件的设置体验不一致。现在架构已趋于稳定：两种清晰的模式（stdio + HTTP），不再有守护进程桥接层，stdio 不会自动启动进程。

对这段不稳定时期造成的影响，我们深表歉意。如果你在使用旧版本时遇到问题，请更新到最新版本，并按照当前的设置指南操作——此前大多数变通方法已不再需要。

同一作者的相关插件：

• wet——网页搜索 + 内容提取
• mnemo——持久化 AI 记忆
• imagine-mcp——图像/视频理解 + 生成
• email——邮件管理
• telegram——Telegram
• better-godot-mcp——Godot Engine
• crg——代码审查知识图谱

所有插件采用相同的架构——安装一次，即可掌握可迁移的使用模式。

文档

完整文档请访问 mcp.n24q02m.com/servers/better-notion-mcp/：

• 设置——适用于 Claude Code、Codex、Gemini CLI、Cursor、Windsurf、mcp.json 的安装方法
• 模式概览——stdio（本地，集成令牌）和 HTTP（远程，Bearer 令牌）
• 多用户设置——按用户划分的凭据命名空间（HTTP 模式）

使用 AI Agent 安装——将以下内容粘贴给你的 AI 编码 Agent：

按照以下步骤安装 MCP 服务 notion： https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-notion-mcp/setup-with-agent.md

工具

八个组合型 Notion 工具（39 项操作）和两个基础设施工具（config、help）：

工具	操作	说明
pages	create、get、get_property、update、move、archive、restore、duplicate	创建、读取、更新和整理页面
databases	create、get、query、create_page、update_page、delete_page、create_data_source、update_data_source、update_database、list_templates	数据库 CRUD 及数据库内的页面管理
blocks	get、children、append、update、delete	读取和操作区块内容
users	list、get、me、from_workspace	列出并获取用户信息
workspace	info、search	工作区元数据和跨工作区搜索
comments	list、get、create	页面评论和讨论回复
content_convert	markdown-to-blocks、blocks-to-markdown	在 Markdown 和 Notion 区块之间转换（使用 direction 参数）
file_uploads	create、send、complete、retrieve、list	将文件上传到 Notion（单部分或多部分）
config	status、setup_status、setup_start、setup_reset、setup_complete、set、cache_clear	检查和管理凭据状态及配置生命周期
help	-	获取任意组合型工具的完整文档（tool_name 参数）

MCP 资源

URI	描述
notion://docs/pages	页面操作参考
notion://docs/databases	数据库操作参考
notion://docs/blocks	块操作参考
notion://docs/users	用户操作参考
notion://docs/workspace	工作区操作参考
notion://docs/comments	评论操作参考
notion://docs/content_convert	内容转换参考
notion://docs/file_uploads	文件上传参考

配置

变量	必填	默认值	描述
NOTION_TOKEN	是（stdio）	-	Notion 集成令牌
TRANSPORT_MODE / MCP_TRANSPORT	否	stdio	将其中任一项设为 http 以启用远程模式（或传入 --http）
MCP_AUTH_MODE	否（http）	multi	multi（来自 MCP_USERS_FILE 的每用户令牌）、token（一个共享令牌，需要 MCP_AUTH_TOKEN_HASH），或 no-auth（仅用于可信/本地场景）
MCP_USERS_FILE	否（http、multi）	~/.hull/users.toml	multi 模式的用户文件
MCP_AUTH_TOKEN_HASH	是（token 模式）	-	共享令牌的 scrypt$ 哈希值（使用 token hash 生成）
MCP_RPM	否（token 模式）	-	token 模式下可选的每分钟请求上限
PORT	否	0（由操作系统分配）	服务端口；显式设置（例如 8080）可绑定固定端口
HOST	否	127.0.0.1	绑定地址（http 模式）

自托管（远程模式）

在自己的主机上运行 HTTP 服务，并通过 MCP_AUTH_MODE 选择一种身份验证模式：

• multi（默认）：在 MCP_USERS_FILE 中列出每位用户；每位用户的 Notion 令牌都存储在其独立的命名空间中（~/.better-notion/subs/<ns>/config.json）。
• token：一个共享 bearer 令牌。使用 token hash 生成哈希值，并将其传入 MCP_AUTH_TOKEN_HASH。
• no-auth：不进行 bearer 检查。仅用于可信的本地网络。

docker run -p 8080:8080 \
  -e TRANSPORT_MODE=http \
  -e PORT=8080 \
  -e MCP_AUTH_MODE=token \
  -e MCP_AUTH_TOKEN_HASH='scrypt$...' \
  n24q02m/notion:latest

Docker Compose（回环）

docker-compose.http.yml 会构建 http 镜像目标，并且仅在主机回环接口（127.0.0.1:8081）上发布，因此其他机器无法直接访问该服务：

export MCP_AUTH_MODE=token
export MCP_AUTH_TOKEN_HASH='scrypt$...'
docker compose -f docker-compose.http.yml up

服务监听地址为 http://localhost:8081/mcp。如需对外开放，请在回环端口前配置自己的 TLS 反向代理。

发布的镜像为多架构版本（amd64 + arm64），托管于 Docker Hub（n24q02m/notion）和 GHCR（ghcr.io/n24q02m/notion）。没有由 n24q02m 托管的 HTTP 端点。

对比

以下按各项核心能力对比 notion 与直接竞品：

能力	notion	makenotion/notion-mcp-server	suekou/mcp-notion-server	awkoy/notion-mcp-server
Markdown 导入/导出	是（页面和块支持往返转换）	否（原始 Notion JSON）	部分支持（实验性，追加 + 可选转换）	是（往返转换 + GFM）
复合工具设计	是（8 个复合工具，39 项操作）	否（22 个映射到端点的工具）	部分支持（简化工具 + 原始 JSON 工具）	是（2 个调度工具，35+ 项操作）
向 Notion 上传文件	是（file_uploads，支持单文件和分段上传）	否	否	是（upload_file，支持单文件和分段上传）
评论	是（comments：列出/获取/创建）	是	是	是
远程 HTTP + bearer 令牌身份验证	是（每用户命名空间或共享令牌）	部分支持（HTTP + bearer 令牌）	否（仅支持 stdio 令牌）	否（仅支持 stdio 令牌）
可自托管	是（Docker、自有 bearer 令牌）	是	是	是
许可证	Apache-2.0	?	MIT	MIT

安全性

• Bearer 令牌身份验证 —— 每用户令牌（multi）或单个 scrypt 哈希共享令牌（token）
• 速率限制 —— HTTP 传输下每 IP 每分钟 120 个请求
• 会话所有者绑定 —— 对待处理的令牌绑定进行 IP 检查 + TTL 限制
• 空值安全 —— 处理 Notion API 的异常情况（comments.list 返回 404、rich_text 未定义）

从源代码构建

git clone https://github.com/n24q02m/notion.git
cd notion
bun install
bun run dev

信任模型

凭据绝不会发送给 n24q02m：没有托管端点。

模式	存储位置	保护措施	谁可以读取你的数据？
HTTP 自托管（multi）	服务器主机上的 ~/.better-notion/subs/<ns>/config.json	服务器数据目录下的文件权限为 0600	服务器运营者以及任何有权访问该主机的人
HTTP 自托管（token）	服务器主机上的 ~/.better-notion/config.json	服务器数据目录下的文件权限为 0600	服务器运营者以及任何有权访问该主机的人
stdio（本地）	~/.better-notion/config.json	文件权限为 0600；机器密钥位于 ~/.better-notion/.secret	仅你的操作系统用户

许可证

Apache-2.0 —— 参见 LICENSE。