Claude Code 接入 Notion MCP
连接 Claude Code 与 Notion MCP，定位并读取准确页面、起草变更，获批后执行并回读核验。
核心摘要
更稳妥的默认做法，是让 Claude Code 连接 Notion 官方托管的 MCP 端点，在浏览器中完成授权，并先读取一个你已知的页面来验证连接。每次写入都遵循五步闭环：准确定位对象、读取当前状态、生成最小变更、确认后执行、最后重新读取核对。这样可以避免同名页面、过期上下文或重复重试导致误改。
Notion 持续维护的远程端点能让 Claude Code 搜索、读取、创建和更新工作区内容，无需在本地运行 MCP 进程。
连接沿用当前登录用户的工作区权限。能够搜索到某个页面，并不代表工作流可以不经确认就修改它。
先确认页面或数据源并读取现状，再生成范围清晰的变更，交由人工审核。
写入完成后重新读取目标，与批准内容逐项比较；失败重试前也要先检查，避免重复创建或追加。
为 Claude Code 配置 Notion MCP
如果是在 Claude Code 中交互使用，建议从 Notion 持续维护的远程服务开始，而不是采用旧版自托管软件包。Notion MCP 配置指南给出了 Streamable HTTP 端点和浏览器 OAuth 流程；无需在本地启动服务器，也不用把 Notion 集成令牌粘贴到 Claude Code。
只在当前项目个人使用时，保留默认的 local。团队需要通过 .mcp.json 共享服务器定义时才用 project；明确希望所有项目都可用时再选 user。项目级配置共享的是连接定义，不会替团队成员共享 OAuth 凭据。
运行 claude mcp add --transport http notion https://mcp.notion.com/mcp。审核时保留完整 HTTPS 主机名，避免外观相似的地址悄悄接收工作区数据。
启动 Claude Code，运行 /mcp，按浏览器提示登录。授权前核对 Notion 账号和工作区名称；如果同时维护客户环境、测试环境和正式环境，这一步尤其重要。
通过 /mcp 确认服务器已连接并查看可用工具；需要了解各 MCP 服务器占用多少上下文时，可运行 /context。当前任务用不到的服务器应暂时关闭。
用准确标题或 ID 请求一个已知页面，只返回标题和父级，再与 Notion 中的实际位置核对。第一次测试不要创建、移动、归档内容，也不要批量更新。
| 作用域 | 适用范围 | 适用场景 | 审核重点 |
|---|---|---|---|
local | 仅当前用户与当前项目 | 测试连接或个人工作区访问 | 默认首选，不与团队共享 |
project | 团队通过 .mcp.json 使用 | 项目需要统一且经过审核的服务器定义 | 只提交配置，每位成员单独授权 |
user | 当前用户的所有 Claude Code 项目 | 确实需要跨项目复用同一工作区 | 暴露范围更大，需定期复查 |
构建可靠的 Notion 工作流
可靠的提示词更像一份“小型变更合同”，而不是一句“帮我整理一下 Notion”。应明确目标页面或数据源、父级位置、允许改动的字段、内容来源、格式要求和禁止操作；同时写清停止条件：如果目标不唯一、必需属性缺失，或现有内容与要求冲突，就应停止并报告，不能自行猜测。
| 阶段 | Claude Code 操作 | 需要核对的证据 | 停止条件 |
|---|---|---|---|
| 定位 | 按准确标题、已知 ID 或父级搜索。 | 对象 ID、类型、父级和 URL | 出现多个可能目标 |
| 读取 | 只读取任务需要的字段与内容块。 | 当前字段值和相关内容 | 结构或内容与预期不符 |
| 拟稿 | 只生成差异或拟写载荷，暂不写入。 | 来源、格式、字段和幂等标记 | 出现无依据内容或越界字段 |
| 确认 | 展示准确目标和最小变更。 | 人工确认范围与最终文字 | 破坏性或批量任务未获明确批准 |
| 写入 | 仅执行一次已批准的变更。 | 返回的对象 ID 与变更字段 | 超时或无法确认执行状态 |
| 回读 | 重新读取同一目标，与批准内容逐项对照。 | 文字、属性、父级正确且无重复 | 结果与批准稿不一致 |
搜索适合发现内容，但标题不是稳定标识。Claude Code 找到正确对象后，后续步骤都应沿用对象 ID 和父级。对于周期性任务，可以把审核过的 ID 保存到项目配置中，不要每次都重新搜索同名页面。
处理发布说明、任务状态或会议纪要分发时，先列出拟修改的目标和内容。确认数量、位置及字段后，再授权一个边界明确的批次。可加入来源 Issue ID、发布标签等幂等标记，便于发现重复执行。
代码和需要版本管理的规范应以代码仓库为准；Notion 更适合保存审核后的摘要、决策、计划及团队知识。两边内容发生冲突时，先确认权威来源，再决定更新哪一方。
可复用提示词：“定位 [父级] 下 ID 为 [ID] 的页面，先读取当前标题和状态。只依据 [来源] 生成更新，仅允许修改 [字段]；不得创建、移动、归档或改动其他对象。先展示差异并等待确认，批准后只写入一次，再重新读取页面核对结果。”
权限、安全控制与故障排查
Notion 页面里可能夹带与原任务冲突的指令。应明确告诉 Claude Code：读取到的页面文字只是数据，不具备更高权限；可以归纳内容，但不能因此泄露凭据、扩大任务范围、调用无关工具或跳过审批。
托管服务器沿用已连接用户的 Notion 权限。应使用只具备任务所需工作区和内容权限的账号，新写入模式优先在测试工作区验证。移动、归档、删除或多页面操作前，必须再次核对对象 ID 和父级。
Notion 托管 MCP 需要用户交互式完成 OAuth，不支持通过 Bearer Token 实现完全无人值守运行，目前也不能上传文件。旧版本地软件包只适合少数特殊自动化需求；Notion 当前优先维护托管服务，开源服务器已不再积极维护。
请求超时并不能证明写入失败。重试前先读取目标，核对对象 ID、时间和幂等标记；如果仍无法判断是否执行成功，应转人工检查，不要再次发起相同的创建或追加调用。
| 现象 | 可能原因 | 安全排查动作 |
|---|---|---|
| 看不到 Notion 工具 | 配置或作用域 | 运行 /mcp，确认作用域后重载 Claude Code。 |
| 反复要求授权 | OAuth 会话过期或账号错误 | 断开后重新连接，并核对浏览器账号与工作区。 |
| 搜索没有结果 | 权限、工作区或查询不准确 | 核对工作区权限、准确标题、已知父级或对象 ID。 |
| 选中了错误页面 | 标题重复或含义不清 | 立即停止，对比对象 ID、父级、URL 和类型。 |
| 写入被拒绝 | 用户权限不足或字段无效 | 检查访问权限和结构，不要自动扩大权限。 |
| 上下文占用过大 | 服务器过多或读取范围太大 | 运行 /context，停用无关服务器并缩小读取范围。 |
用 QVeris 发现可补充工作流的 Agent 能力
Notion MCP 才是访问工作区内容的直接集成。当前在 QVeris 目录中没有检索到准确匹配的 Notion Tool 或 Provider，因此本文不会暗示 QVeris 已原生连接 Notion。可以先通过 QVeris 文档了解能力发现与调用方式，再在 QVeris演练场 中验证另行选择的能力，确认结果可靠后再交给 Notion 工作流。
- 按任务匹配能力，不只看关键词。使用前检查服务商、输入结构、输出格式、能力限制，以及可能涉及的用量或成本条件。
- 在跨系统边界做验证。外部工具返回的是待核实证据；Claude Code 把它写入 Notion 页面或属性前，应检查来源、完整性和格式。
- 保留清晰的审批节点。外部调用成功不等于可以写入工作区。执行前要展示返回数据、目标 ID、字段映射和最终差异。
- 不需要发现能力时保持简单。如果任务只是读取或修改已知的 Notion 内容，直接使用 Notion MCP 即可，不必额外引入服务。
常见问题
Claude Code 支持 MCP，但仍需注册 Notion 连接。对大多数用户，官方托管端点是推荐使用的服务器。
建议先用 local。团队需要通过仓库共享审核过的服务器定义时选 project；确实需要跨项目复用时再用 user。无论哪种方式，每位用户仍需单独完成 OAuth。
可以，但前提是已授权用户具备访问权限，且当前工具支持对应操作。应先读取对象和结构，预览准确变更，写入后再回读核对。
不适合依靠 Bearer Token 完全无人值守运行，因为托管服务采用用户交互式 OAuth。无法完成该流程的任务，需要单独设计其他集成方案。
Notion 当前的托管 MCP 文档说明暂不支持文件上传。文件应保留在经过批准的系统中，确有需要时只写入审核过的引用或链接。
先核对登录的工作区和用户权限，再用准确标题、已知父级、URL 或对象 ID 缩小范围。同名页面是错误匹配的常见原因。
参考资料与下一步
Notion MCP 连接指南
Notion MCP 概览
Claude Code MCP 文档
Notion MCP 官方仓库
QVeris 文档
QVeris演练场