Notion Private API MCP

Notion 私有 API MCP 服务

基于 Notion 私有 API（token_v2）构建的非官方 Notion MCP 服务。 它让 Claude Desktop、Claude Code、Cursor 及其他 MCP 客户端能够完整读写你的整个 Notion 工作区，无需集成令牌，也不必逐页分享。

与基于官方 Notion API 构建的服务不同，本服务使用浏览器会话 Cookie 进行身份验证，因此 LLM Agent 可以即时搜索、读取、创建和编辑你的账号能够查看的任何页面，无需在 Notion 中进行任何设置。本服务基于官方的 @modelcontextprotocol/sdk（stdio 传输）。

---

为什么选择本服务？

	本服务（私有 API）	官方 Notion API / MCP
在 Notion 中设置	无需设置——只需浏览器 Cookie	创建集成并分享每个页面
访问范围	账号能够查看的所有内容	仅显式分享给集成的页面
身份验证	token_v2 会话 Cookie	集成令牌 / OAuth
最适合	个人自动化、全工作区 Agent	生产应用、多用户场景、官方支持
稳定性	⚠️ 脆弱、未公开文档	✅ 稳定、受支持

如果你只想让 Agent 操作自己的工作区，不想折腾集成权限，这是最快的方式。对于生产环境 / 多租户应用，请使用 官方 Notion MCP 服务。

---

目录

• 重要提示：私有 API
• 快速开始
• 工具
• 配置
• 与 MCP 客户端搭配使用
• 提示词示例
• 编写内容
• 故障排除 / 常见问题
• 贡献
• 许可证 · 免责声明

---

⚠️ 重要提示：本服务使用 Notion 私有 API

本服务调用的是 Notion 的未公开内部 API（https://www.notion.so/api/v3）， 而非官方公共 API：

• 身份验证使用你的浏览器 Cookie（token_v2）——这实际上相当于你的账号密码。切勿提交此 Cookie。
• Notion 可能随时更改此 API 或使其失效，使用此 API 也可能违反 Notion 的服务条款。
• 此 API 本质上不稳定，且不适用于生产环境——使用风险自负，并自行承担数据风险。

---

快速开始

git clone https://github.com/kirvigen/notion-private-api-mcp.git
cd notion-private-api-mcp
npm install
export NOTION_TOKEN_V2='your_token_v2'   # see "Configuration" below
npm start

然后在 MCP 客户端中注册此服务（Claude Desktop / Claude Code）。

---

工具

工具	描述
get_page	读取页面区块及其元数据
get_block	读取单个区块
get_block_children	读取页面或区块的直接子区块
get_style_documentation	支持的区块类型和行内注释目录（编写复杂页面前调用）
markdown_to_blocks	预览 Markdown 如何解析为简化的区块 JSON
create_page	根据区块或 Markdown，在另一个页面下创建子页面
append_blocks	将区块 / Markdown 追加到页面（追加到末尾，或指定区块之后）
replace_page_content	替换页面的直接子区块
update_block_text	替换区块的纯文本内容（例如代码区块）
delete_blocks	从页面中移除（归档）直接子区块
sync_markdown_file	根据本地 Markdown 文件创建或替换页面

工具参数定义在 src/server.js 中。

---

配置

完全通过环境变量配置：

变量	必需	描述
NOTION_TOKEN_V2	✅	你的 Notion 会话 Cookie（token_v2）
NOTION_PRIVATE_API_BASE	—	API 基础 URL（默认值：https://www.notion.so）

获取 token_v2

1. 在浏览器中登录 Notion：https://www.notion.so
2. 打开 DevTools（F12）→ Application → Cookies → https://www.notion.so
3. 复制 token_v2 Cookie 的值。

🔒 请像对待密码一样保管它。将它保存在 shell 环境变量或未跟踪的 .env 文件中，切勿提交。

cp .env.example .env   # then edit .env

---

在 MCP 客户端中使用

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "notion-private": {
      "command": "node",
      "args": ["/absolute/path/to/notion-private-api-mcp/src/server.js"],
      "env": { "NOTION_TOKEN_V2": "your_token_v2" }
    }
  }
}

Claude Code

claude mcp add notion-private \
  --scope local \
  --env NOTION_TOKEN_V2='your_token_v2' \
  -- node /absolute/path/to/notion-private-api-mcp/src/server.js

辅助脚本 ./run-desktop.sh 和 ./run-codex.sh 会自动解析仓库路径，并将日志写入 /tmp。

---

提示词示例

连接后，直接与 Agent 对话：

• "在 Notion 中查找我的“Q3 Roadmap”页面并总结内容。"
• "在 下创建一个名为“Meeting notes”的子页面，并添加今天的行动事项。"
• "将这三项任务添加到 的 TODO 列表中……"
• "将本地的 CHANGELOG.md 同步到发布说明页面。"

---

编写内容

用于写入的工具接受纯 JSON 的简化区块格式：

[
  { "type": "heading_1", "text": "Release Notes" },
  { "type": "paragraph", "text": "First paragraph." },
  { "type": "to_do", "text": "Ship the feature", "checked": true },
  { "type": "toggle", "text": "Details", "children": [
    { "type": "bulleted_list_item", "text": "Item one" }
  ]}
]

支持的类型：paragraph、heading_1/2/3、bulleted_list_item、numbered_list_item、 to_do、toggle、quote、callout、code、divider。

你也可以传入 Markdown（支持稳定的子集：标题、段落、项目符号/编号列表、 任务项、引用块、围栏代码、水平线）。请通过你的客户端调用 get_style_documentation，获取权威的机器可读目录。目前尚未实现嵌套列表、表格和行内格式。

---

故障排除 / 常见问题

在哪里获取 token_v2？ 请参阅获取 token_v2。

NOTION_TOKEN_V2 is required — 启动服务的进程未设置该环境变量（请检查 MCP 客户端的 env 块，而不仅仅是 shell）。

我的令牌停止工作了 — Notion 会话结束时（退出登录、更改密码或长时间不活跃），token_v2 会过期。获取新的 Cookie 并更新它。

MemcachedCrossCellError — 多单元格工作区中出现的暂时性 Notion 路由错误。客户端会自动重试并回退到 loadPageChunk；如果出现此错误，请重试该调用。

这违反 Notion 的服务条款吗？ 本工具使用未公开的内部 API。请仅将其用于你自己的账户和数据，并自行承担风险。

---

项目结构

src/
├── server.js         # MCP server: tool registration + stdio transport
├── notion-client.js  # Private-API client (cookie auth, transactions, retries)
├── notion-blocks.js  # Builds Notion block trees from simplified blocks
├── markdown.js       # Markdown → simplified-block parser
└── style-docs.js     # Catalog returned by get_style_documentation

---

贡献

欢迎提交问题和 PR。如果本项目为你节省了时间，请给仓库点个 ⭐ — 这确实能帮助更多人发现它。

---

许可证

MIT © kir.vigen

免责声明

本项目与 Notion Labs, Inc. 无关。它依赖未公开的内部 API；使用本项目即表示你接受所有风险，包括账户可能受到限制，以及 API 变更导致本项目无法使用。请仅使用你自己的数据。