Notion 官方 MCP Server 怎么配:在 Claude Code、Cursor、Codex 里用 OAuth 连 mcp.notion.com 读写笔记

连接 Notion 官方远程 MCP 服务器无需申请 Integration Token 或本地跑 npx。本文按官方文档整理 https://mcp.notion.com/mcp 在 Claude Code、Cursor 与 Codex 的 OAuth 配置步骤及权限排查。

NNathaniel bigo··原创首发·AI 辅助撰写
12 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

  1. Notion 官方托管了远程 MCP 服务器,地址是 https://mcp.notion.com/mcp,采用 Streamable HTTP 传输与 OAuth 授权,不需要在本地安装 Node.js 脚本或手动生成内部集成密钥。
  2. Claude Code 一行命令即可添加:执行 claude mcp add --transport http notion https://mcp.notion.com/mcp,随后在会话里输入 /mcp 完成浏览器登录授权。
  3. Cursor 与 Codex 只需填一个 url 字段:Cursor 写入 mcp.json,Codex 写入 config.toml 后运行 codex mcp login notion 即可拉起授权页面。
  4. AI 只能读写你本人在 Notion 里有权限访问且授权给该工作区的内容;如果搜不到某个页面,优先检查授权时选中的工作区(Workspace)是否正确。
  5. 主力模型订阅与账号配套入口:跑通 MCP 工具链与多文件智能体编码依赖稳定的底层大模型配额,国内免境外卡自助开通可见本站 Claude Code 订阅页、ChatGPT Plus 充值页 与 AI 会员充值总览。

三款主流客户端接入 Notion 官方远程 MCP 对比

图:本站根据 Notion 开发者文档:Connect Notion to your AI assistant with MCP 整理的示意图

本文根据 Notion 开发者文档《Connect Notion to your AI assistant with MCP》《Notion MCP Overview》及 Claude Code 文档整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Notion 或 Anthropic 官方网站。

适用于谁

  • 想在 Claude Code、Cursor 或 Codex 里直接搜 Notion 笔记、改文档或查数据库,不想来回复制粘贴的开发者;
  • 还在找 Notion Integration Secret 密钥,不知道官方已经提供免密钥远程 MCP 的用户;
  • 配好 mcp.notion.com 后遇到搜不到页面、OAuth 弹窗没反应或切换错工作区的人。

一、官方远程 MCP 与旧本地包有什么区别

早期连接 Notion 往往要在后台手动创建内部集成(Internal Integration)、复制密钥,再用本地命令启动进程,还必须逐个页面手动点添加连接(Connections)。

按照 Notion 官方文档现行方案,https://mcp.notion.com/mcp 由 Notion 官方统一托管维护:

  • 免密钥配置:客户端通过浏览器走 OAuth 2.0 授权流程,不在本地明文配置文件里留存静态 Token;
  • 按工作区授权:登录时直接选择要接入的 Notion 工作区,AI 助手在你的账号权限范围内检索页面、数据库和评论;
  • 传输协议更新:官方主推支持 Streamable HTTP 的 /mcp 端点,关于传输方式的技术差异可参考 MCP 的 stdio、SSE 和 Streamable HTTP 有什么区别。

如果你平时主要在网页端对话而非编程工具里查笔记,也可以对比阅读 ChatGPT 怎么连接 Notion。

二、Claude Code、Cursor 与 Codex 配置步骤

1. 在 Claude Code 中配置

  1. 打开系统终端,运行添加远程 HTTP 服务器的命令:
bash
claude mcp add --transport http notion https://mcp.notion.com/mcp
  1. 若希望所有本地代码仓库都能直接调用 Notion,可在命令里加上 --scope user 存为用户级配置;更多作用域说明见 Claude Code MCP 配置教程。
  2. 启动 claude 进入交互界面,输入 /mcp,在列表中选中 notion 并选择认证(Authenticate)。
  3. 浏览器会自动打开 Notion 授权页,确认顶部显示的账号和目标工作区无误后点击允许访问(Allow access)。

高频在终端让 Claude 读需求文档并直接改代码,会话 token 消耗通常较快;如果遇到订阅额度触顶,可在本站查看 Claude Code 订阅充值说明。

2. 在 Cursor 中配置

  1. 打开 Cursor,进入设置(Settings)> Cursor Settings > 工具与 MCP(Tools & MCP),或在项目根目录创建 .cursor/mcp.json(全局配置位于 ~/.cursor/mcp.json)。
  2. 填入以下配置并保存:
json
{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}
  1. 回到 Cursor 的 MCP 面板,看到 notion 旁出现连接或登录提示时点击按钮,在跳出的浏览器页面完成 Notion OAuth 授权。完整的配置文件排错细节见 Cursor MCP 配置教程。

3. 在 Codex(CLI / 桌面端)中配置

  1. 打开 ~/.codex/config.toml(或项目级 .codex/config.toml),新增一段远程服务器声明:
toml
[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"
  1. 在终端运行登录命令触发浏览器认证:
bash
codex mcp login notion
  1. 浏览器提示授权成功后,回到 Codex 即可在对话里直接让它搜索或创建 Notion 页面。若使用 Codex 遇到额度限制,也可在本站了解 ChatGPT Plus 充值。更多参数写法见 Codex 怎么配置 MCP。

三、连上后能做什么与读写边界

完成授权后,Notion 官方 MCP 会向客户端暴露搜索、读取页面、创建页面、更新属性与评论等工具。常见用法包括:

  • 读规格写代码:在提示词里写「在 Notion 搜索标题含『支付重构』的技术方案文档,按里面的字段定义生成 TypeScript 接口」;
  • 查任务数据库:让工具查询指定 Notion 数据库中状态为进行中的条目并汇总进度;
  • 把代码变更写回笔记:代码提交前,让助手在指定父页面下新建一篇接口变更记录,自动整理 Markdown 表格与说明。

需要注意,写操作会直接修改真实工作区里的文档。让 AI 更新长篇笔记前,建议在提示词里明确要求「先列出拟修改的段落或新建子页面,不要直接覆盖原正文」。

Notion 官方 MCP 连接与查不到页面的排查路径

图:本站根据 Notion 开发者文档:Connect Notion to your AI assistant with MCP 整理的示意图

四、授权失败与搜不到页面排查

  1. 搜不到明明存在的页面:多数情况是浏览器里有多个 Notion 工作区,OAuth 授权时选错了个人空间或旧团队空间。在客户端断开并重新发起 /mcp 或重新登录,核对授权页右上角的工作区名称。
  2. 企业工作区提示无权限安装:Notion Enterprise 支持企业统一管理授权(Enterprise-managed authorization)。若工作区管理员限制了外部 MCP 客户端接入,普通成员无法自行放行,需联系管理员在工作区安全后台审批。
  3. 浏览器授权完客户端仍显示未连接:检查本地防火墙或安全软件是否拦截了客户端监听的本地回调端口,保存或授权后在客户端执行一次刷新或重启会话以重新拉取工具列表。

常见问题

问:mcp.notion.com 官方 MCP 收费吗?

答:Notion 官方不单独对 MCP 接口额外按次收费,遵循你当前 Notion 账号所在工作区的权限规则;但 AI 客户端读取长文档返回的内容会正常消耗你在 Claude、Cursor 或 Codex 里的模型上下文额度。

问:地址末尾一定要写 /mcp 吗?

答:要写。Notion 官方文档给出的标准 Streamable HTTP 地址是 https://mcp.notion.com/mcp,只填主域名会导致客户端握手返回 404 或协议识别失败。

问:不想让 AI 继续访问我的 Notion 怎么撤销授权?

答:除了在本地删掉 mcp.json 或运行 claude mcp remove notion,还可以打开 Notion 设置(Settings)里的已连接应用(Connections)列表,找到对应的 MCP 客户端授权记录并移除访问权限。

问:配置好开发环境后,国内没有外币卡怎么开通 Claude 或 ChatGPT 编程订阅?

答:可在 本站充值中心 自助选购卡密开通 Claude Code(Pro / Max) 或 ChatGPT Plus / Pro,全程无需交出账号密码,支持开具增值税发票;实时价格与售后边界(封号不在质保范围)以对应商品页为准。

相关教程

参考资料

  • Notion 开发者文档:Connect Notion to your AI assistant with MCP — https://developers.notion.com/guides/mcp/get-started-with-mcp
  • Notion 开发者文档:Notion MCP Overview — https://developers.notion.com/guides/mcp/overview
  • Claude Code 官方文档:Connect Claude Code to tools via MCP — https://code.claude.com/docs/en/mcp

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    用 ChatGPT 速读英文产品手册、开源文档与 GitHub Issue 并沉淀团队中文内训手册

    团队引入海外 SaaS 工具或开源框架时,全英文文档晦涩冗长、真正的坑全藏在几十页 GitHub Issue 讨论里。本文分享速读拆解英文手册、归类 Issue 排障库以及重构团队中文内训 SOP 的完整实战流程。

    ChatGPT其他 AI 工具0
  2. 02

    用 ChatGPT 写油猴脚本(Tampermonkey)与浏览器书签小工具解决网页繁琐重复操作实战

    每天在后台系统里重复勾选几十个复选框、手工复制网页表格或清理遮挡阅读的侧边栏,既枯燥又浪费时间。本文分享不会写 JS 也能用 F12 配合 ChatGPT 写出油猴脚本与书签小工具的完整实战流程。

    ChatGPT其他 AI 工具0
  3. 03

    用 ChatGPT 写高质量 SQL 窗口函数(RANK / LAG / SUM OVER)做留存与漏斗分析实战

    做用户留存率、复购间隔与有序转化漏斗时,多层自连接既难读又拖垮数据库,窗口函数则是高效解法。本文整理数据库方言喂数规范、CTE 分层提示词以及用内置沙盒先验证再上线的完整实战流程。

    ChatGPT其他 AI 工具0
  4. 04

    ChatGPT 连接 Canva、Figma、Linear、Jira、Dropbox 等第三方应用搜不到数据或授权失效怎么办

    在 ChatGPT 接入 Canva、Figma、Linear、Jira 或 Dropbox 后,明明显示已连接却搜不到文件工单,或老提示授权失效怎么办?本文拆解账号错绑、OAuth 范围漏选、权限继承与管理员拦截 5 步排障法。

    ChatGPT其他 AI 工具0
  5. 05

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  6. 06

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~