/ 目录 / 演练场 / Notion
● 官方 makenotion 🔑 需要你的密钥

Notion

作者 makenotion · makenotion/notion-mcp-server

给你的 agent 读写权限访问团队知识库 —— 规格查询、页面草稿、数据库 CRUD,一个 MCP 搞定。

Notion 官方 MCP。读取页面、创建块、查询数据库、更新属性。把 Notion 变成你的 agent 可以搜索、总结、追加的第二大脑 —— 最简洁的方式让内部文档对 AI 可寻址,无需单独的 RAG pipeline。

为什么要用

核心特性

实时演示

实际使用效果

notion.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "notion",
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "notion": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@notionhq/notion-mcp-server"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add notion -- npx -y @notionhq/notion-mcp-server

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Notion

让 agent 评审你的 PRD 找出漏洞

👤 产品经理、技术主管 ⏱ ~15 min intermediate

何时使用: 你起草了规格书,想在分享给工程团队前做一轮批评性阅读。

前置条件
  • Notion 内部集成令牌 — notion.so/my-integrations → New integration → 复制 secret
  • 与集成共享的页面 — 在页面上:••• → Connections → 添加你的集成
步骤
  1. 获取页面内容
    阅读 Notion 页面 <URL>。用 5 条要点总结这个规格书在提议什么。✓ 已复制
    → 准确的 1 段总结 —— 证明 agent 理解了
  2. 找出规格不明确的地方
    列出规格书中每一个模糊的地方:缺失的错误情况、未定义的边界行为、所有权不清、没有发布计划、没有成功指标。✓ 已复制
    → 编号的漏洞列表,带页面引用
  3. 为评审起草问题
    把这些漏洞转换成 5-10 个评审工程师会问的具体问题。作为一个新的 'Open Questions' 部分追加到 Notion 页面。✓ 已复制
    → 问题块已添加到页面

结果: 一个更紧凑的规格书加上 Open Questions 部分,能在评审会议前启动正确的讨论。

注意事项
  • Agent 虚构规格书中没有的细节 — 在 prompt 中坚持:'只标记漏洞;不要编造事实;引用每个漏洞所在的部分'
  • 长规格书在获取时被截断 — 如果页面有很多块,使用 retrieve_block_children 逐页处理;不要依赖单次 get_page 调用
搭配使用: linear

从 Linear + GitHub 自动生成每日站会页面

👤 工程经理、Scrum Master ⏱ ~10 min intermediate

何时使用: 你运行一个每日 Notion 站会页面,想让它预填昨天的活动。

前置条件
  • 一个 Notion 'Standups' 数据库 — 包含属性:Date (date)、Team (select)、Status (rich_text)
步骤
  1. 收集昨天的活动
    从 Linear 中,列出 ENG 团队在最后 24 小时内移至 Done 的 issue。从 GitHub 中,列出我们团队合并的 PR。✓ 已复制
    → 综合活动列表
  2. 构建站会内容
    格式如下:Wins (已发布)、In-flight (未合并的 PR)、Blockers (标记为 'blocked' 的 issue)、Today's focus (正在进行的 issue)。每个部分保持在 5 条以内。✓ 已复制
    → 格式化的块列表
  3. 创建 Notion 页面
    在 Standups 数据库中创建新页面。Date = 今天、Team = ENG,并将内容粘贴为结构化块(每部分一个 h2)。✓ 已复制
    → 返回页面 URL

结果: 一个预填充的站会页面,为 9 点同步做好准备,节省 15 分钟的仓促。

注意事项
  • 数据库属性名称区分大小写,必须完全匹配 — 在首次运行前用 retrieve_database 列出属性,然后硬编码确切的键名
搭配使用: linear · github

基于你的 Notion 文档构建 Slack 就绪的问答 bot

👤 运维主管、支持经理 ⏱ ~20 min intermediate

何时使用: 新员工不断问相同的问题。你的答案已经写在 Notion 里了 —— 只是找不到。

前置条件
  • 入职文档存在于已知的 Notion 空间中 — 与集成共享父页面,这样所有子页面都继承访问权限
步骤
  1. 搜索工作区
    在 Notion 中搜索匹配 '[用户问题]' 的页面。返回前 5 个页面标题和 URL。✓ 已复制
    → 排序的结果列表
  2. 阅读最相关的
    对于前 2 个匹配项,获取完整内容。引用回答问题的段落。✓ 已复制
    → 逐字引用 + 源 URL
  3. 带引用回答
    用 2-3 句话回答用户的问题,仅基于那些引用。结尾加上:'Source: <url>'。如果文档实际上没有回答,就说出来。✓ 已复制
    → 带引用的回答或诚实的 'not in docs'

结果: 有根据的答案,让人们能自己找到源文档 —— Slack 里不再有 'X 在哪里?' 的问题。

注意事项
  • 当文档实际上没有覆盖时,Agent 编造一个看似合理的答案 — 显式指令:'如果检索到的引用没有回答问题,回复「我在我们的文档中看不到这个 —— 不猜测」'
  • Notion 搜索基于关键词,会遗漏语义匹配 — 如果结果感觉不充分,配合一个合适的 RAG 栈(将 Notion 内容嵌入到向量数据库)

将会议记录转换为 Linear issue

👤 技术主管、产品经理 ⏱ ~10 min beginner

何时使用: 你在 Notion 中记录了会议的粗糙笔记。现在你需要提取行动项。

前置条件
  • 安装了 Linear MCP — 参见 linear 指南
步骤
  1. 阅读会议页面
    阅读 Notion 页面 <URL>。提取每个行动项 —— 任何表述为 'X 会做 Y' 或 'we should Z' 的内容。✓ 已复制
    → 列出所有者(如果提及的话)
  2. 创建前确认
    给我看行动列表。对于每一个,建议 Linear 标题、团队和优先级。还不要创建。✓ 已复制
    → 人工审核的空运行表
  3. 创建已批准的项目
    为第 1、3、5 项创建 Linear issue。将每一个链接回 Notion 会议页面。✓ 已复制
    → 返回 Linear issue URL

结果: 会议行动被真正追踪,而不是丢失在没人再看的 Notion 页面中。

注意事项
  • Agent 把每一个信息性的要点都当成行动 — 在 prompt 中:'只有有明确的所有者或可交付成果的项目 —— 丢弃其他所有项'
搭配使用: linear

审计你的 Notion 文档的陈旧性

👤 文档主管、DevEx 工程师 ⏱ ~20 min intermediate

何时使用: 季度清理 —— 找出 6+ 个月没有更新的文档,这些文档可能不准确。

前置条件
  • 文档区域的根页面 — 例如,/Engineering/Docs —— 与集成共享
步骤
  1. 列出带时间戳的子页面
    列出 'Engineering Docs' 页面下的所有后代页面。对于每一个:标题、URL、last_edited_time、last_edited_by。✓ 已复制
    → 完整清单
  2. 筛选出陈旧的页面
    筛选到最后编辑超过 180 天前的页面。按顶级部分分组。✓ 已复制
    → 每个部分的陈旧列表
  3. 标记以供审核
    对于每个陈旧的页面,在顶部添加一个标注块:'⚠ Needs review — last updated <date>. Ping <last-editor> to confirm.'✓ 已复制
    → 页面已用审核横幅更新

结果: 文档区域中陈旧性是可见的,不是隐藏的 —— 所有者会被提醒要么更新要么删除。

注意事项
  • 某些页面故意作为存档(ADR、验尸报告),不应该获得横幅 — 按标签或父页面筛选 —— 排除 /Archive 下的任何内容或标记为 'historical' 的内容

组合

与其他 MCP 搭配,撬动十倍杠杆

notion + linear

从 Notion PRD 搭建 Linear 项目

阅读 Notion PRD at <URL>,提取可交付成果,并创建一个匹配的 Linear 项目,其中 issue 按里程碑分组。✓ 已复制
notion + github

保持 README 与 Notion 设计文档同步

阅读 Notion 页面 '<API Design>' 并更新我们 api repo 中的 README.md 以匹配 —— 用 diff 打开一个 PR。✓ 已复制
notion + sentry

将每周工程质量报告发布到 Notion 数据库

提取本周每个项目的 Sentry 错误统计,并在 Notion 'Weekly Quality' 数据库中创建新页面。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
search query, filter?: {property, value} 发现 —— 通过关键词在整个工作区查找页面 1 API call
retrieve_page page_id 获取页面元数据/属性 —— 不是内容块 1 API call
retrieve_block_children block_id, start_cursor? 读取实际页面内容 —— 重复调用直到没有 next_cursor 1 API call (may need pagination)
append_block_children block_id, children: Block[] 向页面或特定块下添加内容 1 API call
update_block block_id, {type}: {...} 就地编辑现有块的文本/内容 1 API call
create_page parent: {database_id}|{page_id}, properties, children? 创建新页面 —— 在父页面下或数据库内部 1 API call
query_database database_id, filter?, sorts? 结构化查询 —— 在数据库中筛选/排序条目 1 API call
update_page page_id, properties 更新页面级属性(状态、标签、日期) 1 API call
retrieve_database database_id 写入前自检属性名称/类型 1 API call

成本与限制

运行它的成本

API 配额
Notion:每个集成平均 3 req/sec,允许突发。在规模上会激进地 429。
每次调用 Token 数
每页 500–3000 tokens,取决于块计数
费用
免费 —— API 包含在任何 Notion 计划中
提示
有很多嵌套块的页面读取成本很高。先搜索,只获取目标页面。

安全

权限、密钥、影响范围

最小权限: read_content
凭据存储: 内部集成密钥在环境变量 NOTION_API_KEY
数据出站: 所有调用都到 api.notion.com
切勿授予: update_content insert_content

故障排查

常见错误与修复

object_not_found

页面存在但未与集成共享。打开页面 → ••• → Connections → 添加集成。

validation_error on create_page

你的负载中的属性名称/类型与数据库模式不匹配。先调用 retrieve_database,然后复制确切的键。

429 rate limited

Notion 限制在 ~3 req/sec。在写入之间添加 350ms 睡眠,或通过 append_block_children 批处理(每次调用发送 100 个块,不是 100 次调用)。

页面内容看起来是空的

retrieve_page 仅返回元数据 —— 内容在块中。调用 retrieve_block_children 以获取实际文本。

替代方案

Notion 对比其他方案

替代方案何时用它替代权衡
Confluence MCP你的组织使用 Confluence/Atlassian 而不是 Notion更重的权限模型;agent 工作流往往更慢
Obsidian / filesystem MCP你的知识库是本地 markdown 文件没有多用户同步或权限,但 API 成本为零,读取速度快

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills