SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI开发平台notion-mcp-server

notion-mcp-server

notion-mcp-server 是一个基于 MCP（模型上下文协议）的服务器，让 AI 智能体（Claude、Cursor、ChatGPT、Claude Desktop 等）通过一个令牌和一条命令读写 Notion，覆盖页面、数据库、块、评论、文件与模板。它采用令牌认证，可无头运行于 CI、定时任务和后台代理；通过仅加载三个工具并精简响应，大幅降低上下文占用。代码仓库地址：https://github.com/awkoy/notion-mcp-server

访问官网

工具介绍

用途

notion-mcp-server 是一个 Notion 的 MCP 服务器，用于把支持 MCP 的 AI 智能体（Claude Code、Claude Desktop、Cursor、VS Code、Cline、Zed 等）连接到 Notion，让 AI 用自然语言创建页面、查询数据库、追加块、应用模板、发表评论和上传文件。

主要能力

  • 通过一个令牌认证，可无头运行，适用于 CI、cron 任务、后台代理和自托管部署。官方托管的 Notion MCP 仅支持 OAuth，需要人工点击授权，本服务器采用令牌方式。
  • 节省上下文：官方开源服务器在连接时加载 24 个端点 schema，约 17,163 tokens，并随每次请求重发；本服务器只加载三个工具，约 1,005 tokens，减少 94%（约 17 倍），并且只在任务实际触及时才获取操作 schema。
  • 精简响应：读取同样页面内容，本服务器比官方服务器少用 82% 的 token（88 块页面从 26,071 降至 4,568）；25 行数据库查询少用 81%；页面对象少用 68%。可选的 verbose: true 返回原始 SDK 形态。
  • 内置批量修改与原子回滚、幂等键、限速重试和自愈式验证错误。
  • 三个工具承载 47 个操作：notion_read 执行读取，notion_write 执行写入，notion_describe 返回某个操作的 JSON Schema 及可用示例。
  • 每个 id 字段（page_id、block_id、database_id、view_id 等）也接受 Notion URL。

使用方式

  1. 获取 Notion 令牌：打开 app.notion.com/developers/tokens → + New token → 命名并选择工作区 → Create token → 复制 ntn_… 值。个人访问令牌可见你可访问的一切，无需逐页分享。
  2. 安装配置：
    • 使用 add-mcp 自动发现并写入 MCP 客户端配置（支持 Claude Code、Claude Desktop、Cursor、VS Code、Codex、Gemini CLI、Cline、Windsurf、Zed 等）。-g 装到用户级，-a claude-code 跳过选择器，--all 写入所有客户端。务必保留 --env 标志，否则令牌未写入，服务器启动后每次调用都会鉴权失败。
    • 手动配置写入 mcpServers 块（如 Cursor 的 ~/.cursor/mcp.json、Claude Desktop 的 claude_desktop_config.json、Cline 设置、Zed、Continue 等）。
    • Claude Code 默认走 stdio 的 2025 协议，可在环境变量中设置 MCP_PROTOCOL_NEGOTIATION=auto 以探测 MCP 2026-07-28。
    • Cursor、VS Code（Copilot 智能体模式）有对应的安装入口；VS Code 会把令牌存为 secret input。
    • 仓库提供 gemini-extension.json，可作为扩展安装（令牌存入系统钥匙串，用 npx 启动服务器）。
    • Claude Desktop 无 Node.js 时：从最新 release 下载 notion-mcp-server.mcpb 并双击（或拖入 Settings → Extensions），按提示粘贴令牌。
    • Docker/Podman/OrbStack：stdio 必须加 -i 标志；镜像符合 OCI，Podman、OrbStack、colima、Rancher Desktop、Finch、nerdctl 可用同样标志。
  3. 试用：在新对话中说“用 Notion 创建一个叫 ‘Hello from my agent’ 的页面，并添加一个今天要尝试的三件事的清单。”AI 会调用 notion_write 并回复实时页面链接。

适用场景

  • 查找任务数据库中 Status 为“Doing”的行并判断是否逾期（类型化 where 过滤、扁平化行）。
  • 批量重命名 50 个页面：一次批量调用，10 路并行，幂等重试。
  • 从“Weekly review”模板创建页面并填入摘要。
  • 重写规格页面：通过 get_page_markdown → 编辑 → update_page_markdown 做 markdown 往返。
  • 在昨天的会议记录上评论一段摘要。
  • 上传图表到设计页面（单段和多段上传）。
  • 查看缺陷报告截图并说明问题（get_image 把图片本身交给模型）。

限制与注意事项

  • 权限范围：可读取你可访问的页面，在有编辑权限处创建和更新页面与数据库，以你的身份评论、上传文件；不能访问你看不到的页面、绕过工作区权限、以他人身份操作或更改管理设置。个人访问令牌的范围就是你的账号。
  • 令牌有效期：个人访问令牌自创建起 1 年后过期（Notion 文档）。建议第 11 个月设置提醒。
  • 撤销：app.notion.com/developers/tokens → 令牌旁的 Revoke，立即生效；工作区管理员可从 Settings & members → Connections → All personal access tokens 撤销任何人的令牌。
  • 多数 object_not_found 错误是认证选择错误（内部集成令牌未连接到页面），可改用个人访问令牌。
  • 环境变量 NOTION_ALLOWED_OPERATIONS（允许列表）和 NOTION_BLOCKED_OPERATIONS（阻止列表）接受逗号分隔的预设组或精确操作名；名称不区分大小写，未知令牌忽略并警告，阻止列表优先，允许列表解析为零个操作会禁用一切（fail-closed）。
  • NOTION_CONFIRM_DESTRUCTIVE=true 保留破坏性操作并在执行前通过 MCP elicitation 询问；拒绝或取消返回 confirmation_declined；不支持 elicitation 的客户端返回 confirmation_unavailable。
  • 控制是逐操作而非逐参数：update_page_markdown 是写操作，可替换页面正文，阻止破坏性操作不会禁用它。若要保证不修改，使用 NOTION_ALLOWED_OPERATIONS=read 或 NOTION_READ_ONLY=true。
  • 上传：upload_file 接受 base64、公开 url 或本地路径；路径来源可读取服务器进程可读的任何文件，模型组合路径时应设置 NOTION_UPLOAD_ROOT 限制。
  • 文件 URL：Notion 每次读取都为托管文件生成新的签名 S3 URL（约 1,650 字符，约 500 tokens，有效 1 小时）；NOTION_FILE_URLS=ref 可在精简响应中替换为短小稳定的引用。
  • 远程/HTTP 传输：默认 stdio；设 MCP_TRANSPORT=http 可改为远程端点，在 /mcp 提供 MCP Streamable HTTP。进程是单租户：每个请求都以启动时的 NOTION_TOKEN 身份操作。绑定非回环 HOST 前应设置 MCP_AUTH_TOKEN 并在前方放置认证反向代理。
  • 从 v1.x 或 v2.x 升级：环境变量不变，工具面变化为 notion_read + notion_write，notion_describe 保持原样。详见 MIGRATION.md。
  • 仓库未在该资料中提供其他收费、价格或具体平台支持信息，暂未提供。

同类工具

查看分类