Notion MCP Server 接入指南从 Notion Integration 配置到双传输模式实战基于 klavis 仓库 notion_mcpmark【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本指南围绕 klavis 仓库中 mcp_servers/notion_mcpmark 目录下官方 Notion MCP Server 的完整接入流程展开覆盖 Notion Integration 创建与权限收紧、MCP 客户端Cursor / Claude Desktop / Zed配置、npm 与 Docker 两种运行方式以及 stdio 与 Streamable HTTP 双传输模式与鉴权细节。读完本文你将能够独立完成 Notion MCP Server 的安装、配置、鉴权与工具调用验证并理解其“OpenAPI 规范 → MCP 工具”的底层转换原理。项目定位官方 Notion MCP Server 的本仓库实现Notion 官方已推出名为Notion MCP的远程 MCP 服务器通过标准 OAuth 即可安装无需手工维护 JSON 或 API Token且工具针对 AI Agent 做了 token 消耗优化。而本仓库 mcp_servers/notion_mcpmark 则是该官方 MCP Server 的开源实现它基于 MCP 协议 为 Notion API 提供工具化封装让 Claude、Cursor、Zed 等 MCP 客户端能够通过自然语言直接操作 Notion 页面与数据库。从 package.json 可以看到该包发布名为notionhq/notion-mcp-server当前仓库版本为1.9.1许可证 MITbin 入口为notion-mcp-server。其核心依赖包括modelcontextprotocol/sdk、express、openapi-client-axios、openapi-schema-validator、yargs等说明它本质上是基于 OpenAPI 规范动态生成 MCP 工具的服务器。提示仓库内 src/openapi-mcp-server/README.md 说明该目录是snaggle-ai/openapi-mcp-serverv1 的 fork因上游 v2 与开发方向不兼容fork 后升级了存在漏洞的依赖并简化了配置流程。第一步在 Notion 中创建 Integration在配置 MCP 客户端之前需要先创建一个 Notioninternal integration内部集成打开 https://www.notion.so/profile/integrations开发者门户的集成管理页点击New integration创建一个 internal integration或选择已有的集成创建完成后从Configuration标签页复制以ntn_开头的 Integration Secret后续配置中所有ntn_****占位符都要替换为这个密钥。安全意识主动收紧 Integration 能力虽然本 MCP Server 对 Notion API 暴露范围做了限制例如无法通过 MCP 删除数据库但将工作区数据暴露给 LLM 仍存在非零风险。README 明确建议安全意识强的用户进一步配置 Integration 的Capabilities能力范围。最稳妥的做法是创建一个只读 token在 Integration 设置的Configuration标签页中仅勾选 Read content读取内容权限从而禁止 AI Agent 对工作区内容进行任何写操作。你可以按需决定是否放开 Insert content、Update content 等写权限。第二步将页面和数据库连接到 Integration创建 Integration 后还需要把希望让 MCP Server 操作的页面、数据库与它建立连接有两种方式批量授权进入 Integration 设置的Access标签页点击Edit access勾选需要使用的页面/数据库单页授权打开目标页面点击右上角...菜单选择Connect to integration连接到集成将该页面单独授权给 Integration。这一步极易遗漏如果页面未连接后续调用 Notion API 会返回权限错误如Could not find page或validation_error因此请在调用任何工具前完成授权。第三步在 MCP 客户端中配置 Server方式一npm 运行推荐无需额外依赖适用于Cursor 与 Claude Desktop将以下 JSON 添加到.cursor/mcp.json或claude_desktop_config.jsonmacOS 下 Claude Desktop 配置路径为~/Library/Application Support/Claude/claude_desktop_config.json。方案 A使用NOTION_TOKEN推荐{ mcpServers: { notionApi: { command: npx, args: [-y, notionhq/notion-mcp-server], env: { NOTION_TOKEN: ntn_**** } } } }方案 B使用OPENAPI_MCP_HEADERS高级用法{ mcpServers: { notionApi: { command: npx, args: [-y, notionhq/notion-mcp-server], env: { OPENAPI_MCP_HEADERS: {\Authorization\: \Bearer ntn_****\, \Notion-Version\: \2022-06-28\ } } } } }两种环境变量的优先级与回退逻辑在源码中有明确体现在 proxy.ts 的parseHeadersFromEnv中认证头解析顺序为优先使用 per-request 传入的 Notion tokenHTTP 模式下由x-auth-data头或AUTH_DATA环境变量提供其次尝试解析OPENAPI_MCP_HEADERS仅当其是非空 JSON 对象时才采用若OPENAPI_MCP_HEADERS为空对象或解析失败回退到NOTION_TOKEN环境变量自动构造Authorization: Bearer token与Notion-Version: 2022-06-28请求头。Zed 编辑器在settings.json中添加context_servers配置{ context_servers: { some-context-server: { command: { path: npx, args: [-y, notionhq/notion-mcp-server], env: { OPENAPI_MCP_HEADERS: {\Authorization\: \Bearer ntn_****\, \Notion-Version\: \2022-06-28\ } } }, settings: {} } } }方式二Docker 运行Docker 方式有两条路径适合不想在宿主机安装 Node.js 或希望隔离运行环境的场景。Option 1使用官方 Docker Hub 镜像mcp/notion添加到.cursor/mcp.json或claude_desktop_config.json使用NOTION_TOKEN推荐{ mcpServers: { notionApi: { command: docker, args: [ run, --rm, -i, -e, NOTION_TOKEN, mcp/notion ], env: { NOTION_TOKEN: ntn_**** } } } }使用OPENAPI_MCP_HEADERS高级用法{ mcpServers: { notionApi: { command: docker, args: [ run, --rm, -i, -e, OPENAPI_MCP_HEADERS, mcp/notion ], env: { OPENAPI_MCP_HEADERS: {\Authorization\:\Bearer ntn_****\,\Notion-Version\:\2022-06-28\} } } } }该方案的优势在于使用官方镜像、通过环境变量正确传递 JSON避免命令行转义问题、配置方式更可靠。Option 2本地构建 Docker 镜像仓库根目录提供了可直接构建的 Dockerfile基于node:20-slim先npm ci --ignore-scripts --omit-dev安装生产依赖再npm run build构建产物最后通过npm link全局安装notion-mcp-server可执行文件。首先在仓库根目录构建镜像docker compose build随后在 MCP 配置中加入使用NOTION_TOKEN推荐{ mcpServers: { notionApi: { command: docker, args: [ run, --rm, -i, -e, NOTION_TOKENntn_****, notion-mcp-server ] } } }使用OPENAPI_MCP_HEADERS高级用法{ mcpServers: { notionApi: { command: docker, args: [ run, --rm, -i, -e, OPENAPI_MCP_HEADERS{\Authorization\: \Bearer ntn_****\, \Notion-Version\: \2022-06-28\}, notion-mcp-server ] } } }注意无论采用哪种方式都需要把配置中的ntn_****替换为 Integration 的 Secret。另外本仓库 Dockerfile 的运行时默认以 HTTP 传输模式启动在 5000 端口并禁用了 Bearer 鉴权ENTRYPOINT [notion-mcp-server, --transport, http, --port, 5000, --disable-auth]与 README 中面向桌面客户端的 stdio 示例不同适合作为远程/容器化服务使用。传输模式详解stdio 与 Streamable HTTP该 MCP Server 支持两种传输模式对应不同的客户端场景。STDIO 传输默认标准输入/输出传输是 MCP 最通用的模式被 Claude Desktop 等大多数桌面客户端采用。直接运行# 以默认 stdio 传输运行 npx notionhq/notion-mcp-server # 或显式指定 stdio npx notionhq/notion-mcp-server --transport stdioStreamable HTTP 传输面向 Web 应用或偏好 HTTP 通信的客户端使用 Streamable HTTP 传输# 以 HTTP 传输运行默认端口 3000 npx notionhq/notion-mcp-server --transport http # 指定自定义端口 npx notionhq/notion-mcp-server --transport http --port 8080 # 指定自定义鉴权 token npx notionhq/notion-mcp-server --transport http --auth-token your-secret-token使用 HTTP 传输时服务端点固定为http://0.0.0.0:port/mcp。从 start-server.ts 的 CLI 参数解析逻辑可以确认完整参数包括参数说明默认值--transport type传输类型stdio或httpstdio--port numberHTTP 模式监听端口3000--auth-token tokenHTTP 模式 Bearer 鉴权 token可选无--disable-auth关闭 HTTP 模式 Bearer 鉴权关闭另外HTTP 模式还提供无需鉴权的健康检查端点/health返回status、transport、port等 JSON 信息便于容器编排与监控探活。HTTP 模式的三种鉴权方式Streamable HTTP 传输出于安全考虑强制要求 Bearer token 鉴权提供三种配置方式方式一自动生成 token推荐用于开发npx notionhq/notion-mcp-server --transport http服务器启动时生成安全随机 token 并打印到控制台Generated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab Use this token in the Authorization header: Bearer a1b2c3d4e5f6789abcdef0123456789abcdef0123456789ab方式二命令行指定 token推荐用于生产npx notionhq/notion-mcp-server --transport http --auth-token your-secret-token方式三环境变量指定 token推荐用于生产AUTH_TOKENyour-secret-token npx notionhq/notion-mcp-server --transport http优先级规则若同时提供了命令行参数--auth-token与环境变量AUTH_TOKEN命令行参数优先生效。该逻辑在 start-server.ts 中实现options.authToken || process.env.AUTH_TOKEN || randomBytes(32).toString(hex)——即命令行参数优先其次环境变量最后才是随机生成。发起 HTTP 请求所有发往 Streamable HTTP 端点的请求都必须携带 Bearer token除非--disable-auth# 示例请求MCP initialize curl -H Authorization: Bearer your-token-here \ -H Content-Type: application/json \ -H mcp-session-id: your-session-id \ -d {jsonrpc: 2.0, method: initialize, params: {}, id: 1} \ http://localhost:3000/mcp几点补充来自源码实现该 HTTP 服务采用无状态stateless模式每次POST /mcp请求都会创建一个新的StreamableHTTPServerTransport与MCPProxy实例start-server.ts因此GET /mcp与DELETE /mcp会返回405 Method not allowed鉴权中间件对缺失 token 返回401JSON-RPC 错误码-32001对 token 不匹配返回403错误码-32002每个请求设有 90 秒超时上限避免挂起请求拖垮长连接无论使用哪种传输模式都必须设置NOTION_TOKEN推荐或OPENAPI_MCP_HEADERS环境变量。源码视角MCP Server 如何把 OpenAPI 变成工具理解底层机制有助于排查问题与二次开发。整个服务器遵循“OpenAPI 规范 → MCP 工具 → 真实 API 调用”的流水线加载并校验 OpenAPI 规范init-server.ts 读取scripts/notion-openapi.json通过openapi-schema-validator校验合法性并可通过BASE_URL环境变量覆盖规范中的服务器地址parsed.servers[0].url baseUrl。规范转换为 MCP 工具parser.ts 中的OpenAPIToMCPConverter将 OpenAPI 的每个 operation 转换为 MCP tool处理$ref引用解析、JSON Schema 转换binary格式转换为uri-reference并提示使用本地文件绝对路径、工具名截断超过 64 字符截断等细节。工具调用转发proxy.ts 的CallToolRequestSchema处理器根据工具名查找对应的 OpenAPI operation通过HttpClient.executeOperation执行真实 HTTP 请求并把响应体JSON.stringify后以text类型 content 返回请求失败时返回isError: true及错误详情。并发安全优化init-server.ts中通过模块级getSharedProxyState缓存了解析后的 OpenAPI 规范、转换后的工具定义与 axios 客户端所有并发POST /mcp请求共享这份状态避免每个请求重复解析导致高并发下内存溢出源码注释提到此前在约 300 并发会话、运行约 1 小时后触发 Cloud Run 容器 OOM。token 不入缓存按请求注入。实战示例用自然语言驱动 Notion配置完成后即可在支持 MCP 的客户端Cursor、Claude Desktop、Zed 等中用自然语言操作 Notion。以下三个示例覆盖了 Notion API 的典型调用链示例 1评论页面两次 API 调用指令Comment Hello MCP on page Getting startedAI 会正确规划两次 API 调用v1/search按标题找到 Getting started 页面与v1/comments向该页面添加评论从而完成任务。示例 2创建子页面指令Add a page titled Notion MCP to page Development该指令会在父页面 Development 下新建一个名为 Notion MCP 的页面。示例 3直接引用内容 ID指令Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2对于已知的页面/数据库 ID可直接引用1a6b35e6e67f802fa7e1d27686f017f2这样的 32 位十六进制 ID 精确定位内容省去搜索步骤。开发与发布针对希望本地开发或二次维护该 Server 的开发者# 构建 npm run build # 本地执行通过本地路径 npx npx -y --prefix /path/to/local/notion-mcp-server notionhq/notion-mcp-server # 发布到 npm npm publish --access publicpackage.json 中build脚本为tsc -build node scripts/build-cli.jsdev脚本为tsx watch scripts/start-server.ts热重载开发模式。测试方面src/openapi-mcp-server下内置了 vitest 测试套件覆盖 HTTP 客户端、文件上传、multipart 解析、OpenAPI 解析与 MCP 代理如 proxy.test.ts、http-client.test.ts可作为功能正确性的参考。安全注意事项小结最小权限原则在 Notion Integration 的 Capabilities 中仅开放必要能力如只读场景只勾选 Read content页面授权确保目标页面/数据库已连接到 Integration否则 API 调用返回权限错误token 保护Integration Secretntn_开头与 HTTP 鉴权 token 属于敏感凭据不要硬编码进代码或提交到版本库远程服务暴露面若以容器/远程方式部署 HTTP 模式务必设置强鉴权 token--auth-token或AUTH_TOKEN或在可信内网中使用--disable-auth并利用/health端点做健康检查。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考