AI工具接入教程
每日 MCP Server

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

2026-08-05
文件仓库
支持客户端：
Claude CodeCursorVS CodeContinueCline
MCPNotion知识库协作平台

简介

Notion MCP 是 ModelContextProtocol 官方维护的协作平台集成服务器，通过 Notion API 让 LLM 客户端能够搜索页面、读取内容、创建文档、更新数据库记录。一条 npx 命令即可让 Claude Code、Cursor、VS Code 等 MCP 客户端成为 Notion 知识库助理。本文梳理核心能力、Internal Integration 申请、各客户端配置与实战注意事项。

安装命令

npx -y @modelcontextprotocol/server-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

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

步骤 2：给 Integration 授权页面

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

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

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

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

注意事项

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

相关推荐

查看更多 →
MCP知识管理

Notion MCP：让 AI 读写知识库，把笔记变成可调用数据

Notion MCP 让 Claude/Cursor 直连 Notion，搜页面、读内容、建页面、改属性，让 AI 把散落的知识库变成可调用的结构化数据。本文拆解安装配置、6 个工具用法、5 个实战场景（知识检索、会议纪要入库、需求转页面、批量整理、知识图谱），以及只读与写权限的安全管控。

2026-08-17
#MCP#Notion
MCP编程开发

MCP Resources 实战：让服务端把 8 万行设计文档喂给 Agent，附四套客户端配置与13 行排查表

Tools 是「Agent 问你答」，Resources 是「你问Agent 答」——同一个 MCP Server 里，方向相反的两种能力，而且很多人在写 Server 时只实现了 Tools，漏掉了 Resources。结果是文档、规范、schema、日志这类只读数据只能靠 Agent 一个个调 Tool 去捞，每次捞都要过一次模型判断，成本高还不稳定。本文讲透MCP 四大原语里的第二个：Resources。涵盖 resources/list、resources/read、resources/templates/list 三个方法与 URI 模板机制（RFC 6570 展开规则），以及 Resource 与 Tool 的选型对照（把同一份数据做成 Tool 还是 Resource 的实测差异）。给出一个可运行的「设计文档中心」Server 完整实现（含 40+ 行 TypeScript，含分页、版本快照、访问审计），以及 Claude Code / Cursor / VS Code + Copilot / Trae 四套带中文注释的配置 JSON。三个实战场景：Agent 读设计文档回答「这个接口为什么这么设计」、按版本读取历史 schema 做迁移校验、把资源目录挂进 IDE 侧边栏。另含资源数量膨胀到 500+ 时的分页与 URI 命名规范、五条安全红线（为什么资源 URI 绝不能暴露绝对路径和凭据），以及 13 行故障排查表。

2026-10-13
#MCP#Model Context Protocol
MCP开发

MCP Elicitation 实战：让服务端在缺参数时反向向用户提问——受限 Schema 设计 + 四套客户端配置 + 13 行排查表

写 MCP Server 的人迟早会遇到一个尴尬场景：工具必填参数用户没给，服务端要么猜一个（猜错就出事），要么返回一个干巴巴的「缺少参数 xx」让 Agent 自己去追问（Agent 经常追问得驴唇不对马嘴）。MCP 协议里的 Elicitation 就是为这个场景设计的第三个「反向能力」——服务端可以在执行过程中主动向客户端发起一次提问，由客户端把问题渲染成表单弹给用户，用户填完再回传，全程服务端不需要自己实现任何 UI、不需要存任何凭据。本文讲透它的机制与边界：elicitation/create 请求的完整结构、为什么 requestedSchema 被刻意限制成只支持原始类型（这是安全设计不是能力不足）、用户的三种响应（accept / decline / cancel）各自的语义差异、以及最关键的——为什么不能在 Elicitation 里索取密码和 API Key。含 TypeScript SDK 完整实现（含类型定义与降级路径）、Claude Code / Cursor / VS Code + Copilot / Trae 四套带中文注释的配置、三个实战场景（部署确认 / 缺失参数补全 / 敏感操作二次确认）、与 Sampling / 传统参数校验的选型对比、六条安全注意事项，以及 13 行故障排查表。

2026-10-12
#MCP#Model Context Protocol
MCP开发

MCP Roots 与 Sampling 实战：让服务端主动划边界、反向要推理——四套客户端配置 + 14 行排查表

多数人写 MCP Server 只用到 Resources / Tools / Prompts 三项，Roots 和 Sampling 这两个反向能力基本闲置，结果就是 Server 既不知道自己该在哪干活，也没有推理能力。本文把这两个方向的能力讲透：Roots 是客户端告诉服务端「工作区边界在哪」的机制（URI 列表、roots/list 双向协商、listChanged 动态通知、路径穿越的必修防御），Sampling 是服务端反过来向客户端的 LLM 请求一次推理的机制（服务端不知道任何 API Key，模型由客户端挑、账由客户端付、人可以卡在中间审批）。含 TypeScript SDK 完整实现代码（含 sampling/createMessage 的类型定义与 human-in-the-loop 回调）、Claude Code / Cursor / VS Code + Copilot / Trae 四套带中文注释的配置、三个实战场景（单仓守卫 / 日志归因摘要 / 隐私脱敏代理）、与其他方案的选型对比表、六条安全注意事项，以及 14 行故障排查表。

2026-10-10
#MCP#Model Context Protocol