ACORG docs

主题

Notion MCP ​

Notion MCP 是 Notion 官方托管的 MCP 服务,用于让 AI 客户端在用户授权后读取和写入 Notion 工作区内容。

官方文档:https://developers.notion.com/guides/mcp/get-started-with-mcp

适用场景 ​

  • 读取需求文档、会议纪要、项目计划和团队规范。
  • 根据 Notion 页面生成任务拆解、实现计划或验收清单。
  • 让 Agent 在授权范围内更新页面、整理说明或补充评论。
  • 在 ChatGPT、Codex、Claude Code、Cursor、VS Code、Windsurf 等客户端中接入团队知识库。

服务地址 ​

Notion 官方推荐使用托管 MCP 服务:

text
https://mcp.notion.com/mcp

旧客户端如果只支持 SSE,可使用:

text
https://mcp.notion.com/sse

Notion MCP 使用 OAuth 授权。官方文档说明它不支持 bearer token 认证,因此通常需要用户完成授权流程,不适合完全无人值守的云端自动化。

Codex 配置 ​

在 Codex 配置中添加:

toml
[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

然后执行登录:

bash
codex mcp login notion

完成 OAuth 流程后即可使用。需要项目级共享时,可把相同配置放到项目 .codex/config.toml。

Claude Code 配置 ​

bash
claude mcp add --transport http notion https://mcp.notion.com/mcp

然后在 Claude Code 中运行 /mcp,按提示完成 OAuth。官方文档还说明可通过 --scope 控制 local、project、user 等安装范围。

Cursor 配置 ​

全局配置可在 Cursor Settings -> MCP 中添加:

json
{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

如果要随项目共享,可创建 .cursor/mcp.json 并写入相同配置。

VS Code 配置 ​

在工作区创建 .vscode/mcp.json:

json
{
  "servers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

之后通过 Command Palette 执行 MCP: List Servers,启动 Notion server 并完成 OAuth。

不支持 remote MCP 的客户端 ​

如果客户端只支持本地 stdio MCP,官方文档建议可用 mcp-remote 桥接:

json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
    }
  }
}

从 Notion 应用内连接 ​

也可以从 Notion 应用内发起连接:

  1. 打开 Notion Settings。
  2. 进入 Connections -> Notion MCP。
  3. 选择 AI 工具并完成 OAuth。

注意事项 ​

  • 只授权必要的页面、数据库或工作区范围。
  • 私有客户信息、密钥、合同、财务数据不要暴露给 AI 客户端。
  • Notion 内容常是需求和讨论来源,关键事实仍要回到代码、issue 或正式合同核验。
  • 写入 Notion 前应要求 Agent 列出将修改的页面和字段。
  • 如果认证异常,先断开连接或清除认证,再重新 OAuth。

官方 FAQ 要点 ​

  • Notion MCP 需要用户 OAuth 授权,不适合完全无人参与的 bearer token 自动化。
  • 当前 Notion MCP 不支持文件上传;需要文件上传时使用 Notion 文件上传 API。
  • 官方托管 MCP 是推荐方案;旧的开源 server 已不再作为首选。

相关文档 ​