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

notion-mcp-server

Notion 官方的 MCP 服务器，用于通过 Notion API 将 Notion 工作区接入支持 MCP 的 AI 客户端。该仓库为自托管实现，官方说明其已不再主动维护和支持，建议改用官方托管的 Remote Notion MCP。项目当前版本 2.0.0，迁移到 Notion API 2025-09-03，以数据源（data source）作为数据库的主要抽象，共提供 22 个工具，并支持将页面内容以增强 Markdown 读写以节省 token；支持 stdio 与 Streamable HTTP 两种传输方式，可通过环境变量或请求头配置 Notion 集成令牌。

访问官网

工具介绍

用途

Notion MCP Server 是 Notion 官方的 Model Context Protocol（MCP）服务器实现，用于把 Notion API 接入支持 MCP 的 AI 客户端，使 AI 能够搜索、读取和编辑 Notion 中的页面与数据库内容。

官方在该仓库中明确表示：本仓库是独立的自托管 MCP 服务器实现，已不再被主动维护或支持，推荐改用官方托管的 Remote Notion MCP。官方后续将只对 Remote Notion MCP 提供主动支持，并可能在未来下线本自托管仓库；此处的 issue 与 pull request 也不会被主动监控。

主要能力

  • 通过 MCP 暴露 Notion API 能力，当前共 22 个工具（v1.x 为 19 个）。
  • 2.0.0 版本迁移到 Notion API 2025-09-03，引入 data source 作为数据库的主要抽象。
  • 移除了 post-database-query、update-a-database、create-a-database 三个工具，分别由 query-data-source、update-a-data-source、create-a-data-source 取代。
  • 数据源相关工具包括：query-data-source（按过滤器与排序查询数据源/数据库）、retrieve-a-data-source（获取数据源元数据与 schema）、update-a-data-source（更新数据源属性）、create-a-data-source（创建新数据源）、list-data-source-templates（列出数据源中可用模板）。
  • 另提供 move-page（将页面移动到不同父位置）、retrieve-a-database（获取数据库元数据，包含其数据源 ID 列表）。
  • 参数变化：所有数据库操作改用 data_source_id 而非 database_id；搜索过滤值由 ["page", "database"] 变为 ["page", "data_source"]；创建页面现在同时支持 page_id 与 database_id 作为父级（用于数据源）。
  • 页面内容以增强 Markdown 而非 block JSON 形式暴露，官方称对 AI 代理显著更省 token：retrieve-page-markdown（以 Markdown 读取页面完整内容，GET /v1/pages/{page_id}/markdown，传 include_transcript: true 可内联会议记录转录）、update-page-markdown（以 Markdown 编辑页面内容，PATCH /v1/pages/{page_id}/markdown，可用 replace_content 覆盖整页，或用 update_content 做定位查找替换）。
  • 上述 Markdown 端点需要 Notion API 版本 2026-03-11；服务器会按操作从 OpenAPI 规范中读取 Notion-Version 头，因此这些工具使用 2026-03-11，其余 API 继续使用 2025-09-03，无需手动配置。若通过 OPENAPI_MCP_HEADERS 自行设置 Notion-Version，则该值对所有工具优先生效。

使用方式

官方说明的配置要点如下：

  • 在 https://www.notion.so/profile/integrations 创建新的内部集成或选择已有集成。官方提示，尽管限制了 Notion API 暴露范围（例如无法通过 MCP 删除数据库），但将工作区数据暴露给 LLM 仍存在非零风险，注重安全的用户可进一步配置集成的 Capabilities，例如仅授予“Read content”以创建只读令牌。
  • 确保相关页面和数据库已连接到该集成：可在内部集成设置的 Access 标签页编辑访问权限并选择页面；也可在目标页面上点击三点菜单，选择“Connect to integration”逐个授予页面访问。
  • 将配置加入 .cursor/mcp.json 或 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json），或加入 settings.json。
  • 可使用 Copilot CLI 交互式添加 MCP 服务器，也可创建或编辑配置文件 ~/.copilot/mcp-config.json 并写入配置。
  • Docker 运行有两种选项：使用官方 Docker Hub 镜像时，可通过 NOTION_TOKEN（推荐）或 OPENAPI_MCP_HEADERS（高级用法）配置。
  • 也可在本地构建并运行 Docker 镜像，然后写入相应客户端配置。
  • 需将示例中的 ntn_**** 替换为你的集成密钥，可在集成配置标签页中找到。

传输方式

  • 默认传输模式使用标准输入输出（stdio），这是大多数客户端（如 Claude Desktop）使用的标准 MCP 传输。
  • 对于基于 Web 的应用或偏好 HTTP 通信的客户端，可使用 Streamable HTTP 传输；默认情况下服务器位于 http://127.0.0.1:<port>/mcp。
  • Streamable HTTP 传输要求 bearer token 认证，有三种选项：服务器会生成安全随机令牌并写入权限受限的文件；命令行参数 --auth-token 优先于 AUTH_TOKEN 环境变量。
  • 只有在显式使用不安全标志 --unsafe-disable-auth 时才能禁用 bearer token 认证。官方警告该标志不安全，服务器可能因 DNS 重绑定而对你访问的页面可达，只应在隔离网络中使用。禁用认证时，服务器会通过检查 Host 和 Origin 头与配置的本地主机和回环主机来启用 DNS 重绑定保护；旧的 --disable-auth 标志仍作为已弃用别名被接受，但会打印警告。
  • 所有对 Streamable HTTP 传输的请求必须在 Authorization 头中包含 bearer token。
  • 使用任一传输模式时，需设置 NOTION_TOKEN（推荐）或带 Notion 集成令牌的 OPENAPI_MCP_HEADERS 环境变量。

令牌透传

默认情况下，服务器在启动时内置单一令牌向 Notion 认证，从而将一次部署锁定为单个 Notion 集成。若要一次部署服务多个集成，可启用令牌透传，让每个客户端按连接提供自己的 Notion 集成令牌：客户端在 initialize 请求中使用专用的 Notion-Token 头发送其 Notion 令牌。每个连接的令牌解析顺序为：Notion-Token 头（首选，明确无歧义，且可与服务器自身的 Authorization 网关认证并存；若存在则必须是有效 Notion 令牌，否则请求以 401 拒绝）；Authorization: Bearer ntn_****（仅当服务器自身的 bearer 认证关闭，即 --unsafe-disable-auth 时，该头可自由承载 Notion 令牌）；否则使用启动环境令牌（NOTION_TOKEN / OPENAPI_MCP_HEADERS，若已设置），因此透传与默认集成可在同一部署中共存。只有带 Notion 令牌前缀（ntn_、旧式 secret_）的值才会被视作 Notion 令牌，因此服务器网关密钥与租户的 Notion 令牌不会冲突。每个令牌绑定到其 MCP 会话；令牌从不记录（仅输出经过脱敏的前缀）。官方提示这是刻意的令牌透传设置，应始终通过 TLS 部署，并优先保留服务器自身 bearer 认证（--auth-token）作为多租户流量前的网关。

本地测试

官方给出的本地测试方式如下：在仓库根目录运行 npm link 创建指向 notion-mcp-server 包的机器全局符号链接；将配置片段合并到 Cursor 的 mcp.json（或要测试的其他 MCP 客户端）；完成后在仓库根目录运行 npm unlink 清理。

适用场景

适用于希望通过 MCP 让 AI 客户端访问、检索和编辑 Notion 页面与数据库的工作流，例如用自然语言查询数据库、评论、创建页面等。官方示例说明，使用特定指令时 AI 会正确规划两次 API 调用（v1/search 与 v1/comments）来完成任务；类似地，另一条指令会在父页面“Development”下新增名为“Notion MCP”的页面。也可以直接引用内容 ID。

限制

  • 仓库为自托管实现，官方表示不再主动维护和支持，可能未来下线，issue 与 PR 不被主动监控；远程 MCP 相关问题不应在此提交，应联系 Notion 支持。
  • 升级到 v2.0.0 无需改代码，MCP 工具会在服务器启动时自动发现，AI 客户端会自动看到新工具名与参数，但旧的数据库工具不再可用；若硬编码了旧数据库工具名或提示词，需要更新为新的数据源工具。
  • retrieve-a-database 仍可用，返回数据库元数据及数据源 ID 列表；若要获取特定数据源的 schema 与属性，应使用 retrieve-a-data-source。
  • Markdown 页面工具依赖 Notion API 版本 2026-03-11，而其余 API 使用 2025-09-03。
  • 官方未在本资料中提供具体收费与价格信息，暂未提供。

同类工具

查看分类