notion-mcp

---

功能

• 搜索 — 在整个工作区中进行全文搜索
• 导出 — 将任意页面下载为整洁的 Markdown（标题、列表、待办事项、代码块、表格、链接、带可查看 URL 的图片）
• 导入 — 将 Markdown 写入 Notion 页面（替换内容），支持字符串或本地文件
• 追加 — 将 Markdown 添加到页面末尾，不影响现有内容
• 创建 — 新建子页面，可选择用 Markdown 字符串或文件预填内容
• 图片 — 将本地图片上传到页面，或引用外部 URL
• 评论 — 列出未结束的讨论、添加新评论、回复讨论串
• 一条命令完成设置 — npx @shck-dev/notion-mcp init：粘贴浏览器中的“Copy as cURL”，即可提取并保存凭据
• 提示词和资源 — 提供 notion_setup 提示词和 notion://guide 资源，方便在客户端中完成入门设置
• 零设置障碍 — 使用与 Notion 网页应用相同的内部 API；只要能在浏览器中看到内容，此服务就能访问

工具

工具	描述
notion_search	在工作区的所有页面中进行全文搜索
notion_export_page	将任意 Notion 页面导出为 Markdown；图片链接会解析为可查看的 CDN URL（传入 image_dir 可改为将图片下载到本地）
notion_import_page	将 Markdown 写入 Notion 页面 — 替换所有现有内容
notion_import_page_from_file	将本地 .md 文件写入页面 — 替换所有内容
notion_append_to_page	将 Markdown 追加到页面末尾（不会破坏现有内容）
notion_append_to_page_from_file	将本地 .md 文件追加到页面末尾（不会破坏现有内容）
notion_create_page	创建新的子页面，可选择预填 Markdown 内容
notion_create_page_from_file	根据本地 .md 文件创建新的子页面
notion_add_image	在页面末尾添加图片 — 本地文件会上传到 Notion，http(s) URL 则按原样引用
notion_list_comments	列出页面上未结束的讨论串
notion_add_comment	开始新讨论 — 可添加行内评论（锚定到文本）或块级评论
notion_reply_comment	回复现有讨论串
notion_init	粘贴浏览器中的“Copy as cURL”以提取并保存凭据

为什么不使用官方 Notion API？

	此 MCP 服务	官方 Notion API
设置	从 DevTools 中复制 3 个值	创建集成、获得管理员批准、共享页面
页面访问权限	你能看到的所有内容	仅限明确共享的页面
Markdown	双向支持（导出 + 导入）	只读的块 API
身份验证	Cookie（token_v2）	OAuth / 集成令牌

权衡：内部 API 未公开文档，可能会发生变化。令牌会定期过期（需从浏览器中重新获取）。

快速开始

最简单：交互式设置

npx @shck-dev/notion-mcp init

在 Chrome 中打开 Notion → 开发者工具（F12）→ 网络 → 点击任意一个 notion.so/api/v3/… 请求 → 右键 → 复制为 cURL，然后粘贴并按 Ctrl-D。系统会提取你的令牌、用户 ID 和工作区 ID，并保存到 ~/.notion-mcp/config.json。然后注册服务——无需 env 块：

claude mcp add notion -- npx @shck-dev/notion-mcp

想手动设置这三个值？请看下面的步骤。

1. 从浏览器获取凭据

1. 在 Chrome 中打开 notion.so
2. 按 F12 → 应用程序 → Cookie → www.notion.so
3. 复制 token_v2 Cookie 值 → NOTION_TOKEN
4. 按 F12 → 网络选项卡，在 Notion 中执行任意操作
5. 找到一个发往 api/v3/* 的 POST 请求，点击它
6. 从请求标头中复制 x-notion-active-user-header → NOTION_USER_ID
7. 从请求正文（载荷）中找到 spaceId → NOTION_SPACE_ID

2. 配置 MCP 客户端

Claude Code

claude mcp add notion -- env NOTION_TOKEN=your_token NOTION_USER_ID=your_user_id NOTION_SPACE_ID=your_space_id npx @shck-dev/notion-mcp

Claude Desktop / Cursor / 任意 MCP 客户端

添加到你的 MCP 配置中（claude_desktop_config.json、.cursor/mcp.json 等）：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["@shck-dev/notion-mcp"],
      "env": {
        "NOTION_TOKEN": "your_token_v2_value",
        "NOTION_USER_ID": "your_user_id",
        "NOTION_SPACE_ID": "your_space_id"
      }
    }
  }
}

要求

• Node.js ≥ 18（用于 npx）——或使用 Bun。发布的服务已编译为兼容 Node.js 的 JS，因此运行时不再需要 Bun。

限制

• 内部 API——未公开文档，可能会随 Notion 更新而失效
• 令牌过期——token_v2 会定期过期；身份验证失败时，请从浏览器重新获取
• 数据库——数据库/集合页面尚不能导出行；子页面会呈现为链接，这类页面会返回说明性提示，而非空输出
• 块粒度——导入会替换所有内容，追加会添加到末尾（无法就地编辑单个块）
• 有损 Markdown——转换期间，某些复杂格式可能会简化（例如，导入时嵌套列表会扁平化）
• 外部图片——通过 notion_add_image 添加（或嵌入 Markdown 中）的 http(s) 图片 URL 会原样引用，不会重新上传到 Notion

许可证

MIT