Notion MCP：让 LLM 读写 Notion 数据库、页面与块的官方服务器

简介

Notion MCP 是 ModelContextProtocol 官方仓库维护的协作平台集成服务器。它把 Notion API 包装为 MCP 工具，让任何兼容 MCP 的客户端都能通过统一协议操作 Notion，无需各自实现 OAuth 流程、无需处理 webhook、无需封装分页逻辑。

对 Notion 重度用户而言，这意味着：让 AI 助理直接帮你"搜一下我知识库里关于 OKR 的页面"、"把这段会议纪要写入本周的 Notes 数据库"、"读取那张 Database 的所有未完成任务"。

核心能力

工具名	用途	关键参数
`notion_search`	搜索页面与数据库	`query`、`filter`、`page_size`（默认 10）
`notion_get_page`	读取页面属性与块内容	`page_id`
`notion_get_block`	读取单个块（段落、列表等）	`block_id`
`notion_get_blocks`	读取页面所有子块	`block_id`、`page_size`、`cursor`
`notion_create_page`	创建新页面	`parent_id`、`title`、`content`、`icon`
`notion_update_page`	更新页面属性	`page_id`、`properties`
`notion_append_block`	追加内容到页面末尾	`block_id`、`children`
`notion_query_database`	查询数据库记录	`database_id`、`filter`、`sorts`
`notion_create_database`	创建新数据库	`parent_id`、`title`、`properties`

支持的块类型：paragraph、heading_1/2/3、bulleted_list、numbered_list、to_do、code、quote、callout、divider、image、bookmark。

申请 Notion Integration Token

步骤 1：创建 Internal Integration

访问 https://www.notion.so/my-integrations
点击 + New integration
填写名称（如 MCP Assistant）→ 选择关联的 Workspace
类型选 Internal（仅自己可见，无需 OAuth）
保存后复制 Internal Integration Secret（形如 ntn_xxxxxxxxxxxx 或 secret_xxxxxxxxxxxx）

步骤 2：给 Integration 授权页面

关键步骤：Integration 默认无法访问任何页面，必须手动分享。

打开你想让 AI 访问的 Notion 页面或数据库
右上角 ••• → Connections → 搜索刚创建的 Integration 名
点击添加 → 确认

步骤 3：复制页面/数据库 ID

从 Notion URL 提取 ID：

https://www.notion.so/Workspace/My-Page-1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                    这 32 位就是 page_id

数据库 ID 同理（在数据库视图的 URL 中）。

各客户端配置示例

Claude Code（CLI）

编辑 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-notion"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_your_token_here\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

注意：Notion MCP 通过 OPENAPI_MCP_HEADERS 环境变量传递认证头，而不是单独的 token 变量。

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-notion"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_your_token_here\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

VS Code（Continue 插件）

编辑 ~/.continue/config.json：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-notion"]
        },
        "env": {
          "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_your_token_here\",\"Notion-Version\":\"2022-06-28\"}"
        }
      }
    ]
  }
}

Cline 插件

通过 Cline: MCP Settings 命令打开 cline_mcp_settings.json，结构与 Claude Desktop 一致。

实战场景

场景 1：让 Claude Code 做"知识库检索助理"

搜索我 Notion 里所有标题包含「2026 Q3」的页面，
按修改时间倒序整理成表格，
包含：标题 / 修改时间 / 页面链接。

Claude Code 会调用 notion_search → 解析结果 → 格式化输出。

场景 2：让 Cursor 做"任务管理自动化"

查询我的「Tasks」数据库，筛选 status != "Done" 且 due_date <= today 的任务，
按优先级排序，
把高优先级任务追加到「今日聚焦」页面。

Cursor 会调用 notion_query_database（带 filter）→ 处理结果 → notion_append_block。

场景 3：让 VS Code 做"会议纪要写入器"

把以下会议纪要写入我 Notion 的「Meeting Notes」数据库：
- 标题：2026-08-05 产品评审
- 日期：2026-08-05
- 参会人：张三、李四
- 内容：{meeting_content}

创建后把页面链接返回给我。

Cline + Continue 会调用 notion_create_page（指定 parent 为数据库）→ 返回 URL。

场景 4：让 Claude Code 做"文档摘要生成器"

读取我 Notion 里 page_id 为 1a2b3c4d... 的页面，
提取所有 heading_2 块作为章节标题，
对每个章节生成 50 字摘要，
追加到页面末尾作为「TL;DR」section。

Claude Code 会调用 notion_get_blocks → 过滤 heading → 逐个摘要 → notion_append_block。

与 Google Drive MCP 的对比

维度	Notion MCP	Google Drive MCP
数据模型	块结构（树形）	文件（扁平）
数据库能力	✅ 原生 Database	❌ 仅 Sheets
全文搜索	✅ `notion_search`	⚠️ 需 Google 搜索语法
结构化查询	✅ filter + sorts	❌
块级编辑	✅ 精确到段落	❌ 整文件覆盖
OAuth 复杂度	低（Internal Token）	高（OAuth 流程）
适用场景	知识库、任务管理	文档存储、跨设备

建议按使用习惯二选一：Notion 用户装 Notion MCP，Google 用户装 Drive MCP。若同时用两个生态，两个都装。

注意事项

Token 保密：Integration Secret 切勿提交到 Git，用 .env 或系统密钥链管理。
页面授权：Integration 只能访问被显式分享的页面，未分享的页面即使搜索也返回空。
API 限流：Notion API 限制约 3 次/秒，超出返回 429。MCP 服务器已内置退避，但批量操作仍需注意。
Notion-Version：OPENAPI_MCP_HEADERS 中的 Notion-Version 必须指定（建议 2022-06-28），否则部分字段不返回。
块大小限制：单次 notion_append_block 最多 100 个子块，超过需分批。
富文本格式：Notion 的 bold/italic/color 用 JSON 结构表达，不是 Markdown。MCP 服务器支持 Markdown 输入自动转换，但复杂样式可能丢失。
数据库属性类型：query database 的 filter 必须按属性类型写（select / multi_select / date / number 语法不同），建议先 notion_get_page 查看 schema。
子页面继承权限：在被分享的页面下创建子页面，子页面自动继承 Integration 访问权。
中文搜索：Notion 全文搜索对中文支持良好，但分词粒度较粗，建议关键词短而准。

安全建议

最小权限 Integration：只勾选实际需要的 Capabilities（Read/Insert/Update）
页面级授权：只分享必要的页面或数据库，不要分享整个 Workspace
操作审计：Notion 会在页面历史中记录 Integration 的编辑，定期检查
Token 轮换：每 90 天在 Integration 设置页重新生成 Secret
测试 Workspace：先用测试 Workspace 验证，再接入生产 Workspace

小结

Notion MCP 是 Notion 用户最直接的 AI 知识库入口：一个 Internal Token、若干页面授权，就能让任意 MCP 客户端读写 Notion。对于需要"搜索知识、管理任务、写入纪要、查询数据库"的办公场景，几乎是必装组件。建议搭配 Filesystem MCP（管理本地代码）和 Slack MCP（消息协同）组成企业办公三件套。

下一篇我们会讲 GitHub MCP，看如何让 LLM 直接操作仓库、PR、Issue。