Notion MCP Server Skill 技能

技能简介

Notion MCP Server 是 Notion 官方开源的 Model Context Protocol（MCP）服务器，将 Notion API 以 MCP 工具集的形式暴露给 AI 编程助手。通过标准化的 stdio 或 Streamable HTTP 传输协议，AI Agent 可以直接搜索、读取和编辑 Notion 工作空间中的页面与数据库内容，无需额外部署本地服务或维护 API 令牌。

核心能力

1. 22 个 MCP 工具：涵盖页面搜索、Markdown 读写、数据库查询、数据源操作、评论管理、页面移动等完整 Notion 操作集合
2. Markdown 原生读写：retrieve-page-markdown 和 update-page-markdown 工具以 Markdown 格式交换内容，大幅降低 Token 消耗
3. 双重传输模式：支持 stdio（Claude Desktop、Cursor 等）和 Streamable HTTP（Web 应用）两种运行模式
4. Token 节省：相比直接调用 Notion Block JSON，Markdown 模式 Token 消耗减少约 60%~70%
5. 多租户令牌透传：HTTP 传输模式支持每个客户端携带自己的 Notion 集成令牌
6. 自动 OAuth 权限感知：通过 Notion 页面共享权限体系，AI 只能访问已授权内容
7. 数据源 API 2025-09-03：全面支持 Notion 最新数据源抽象
8. 安全认证：HTTP 模式提供 Bearer 令牌认证和 DNS 重绑定保护

安装配置

1. 环境准备：Node.js >= 18，本地 Notion 集成令牌（ntn_ 开头）
2. 获取集成令牌：访问 notion.so/profile/integrations 创建内部集成，配置需要访问的页面范围
3. 客户端配置：Claude Desktop 示例：{"mcpServers": {"notionApi": {"command": "npx", "args": ["-y", "@notionhq/notion-mcp-server"], "env": {"NOTION_TOKEN": "ntn_xxxx"}}}}
4. Docker 方式：使用官方镜像 mcp/notion，通过 NOTION_TOKEN 环境变量注入令牌

使用步骤

1. 在 Notion 中创建内部集成并授权需要访问的页面
2. 将配置加入 AI 编程工具的 MCP 配置文件
3. 重启 AI 编程工具使 MCP 服务器加载
4. 通过自然语言指令让 AI 完成 Notion 页面搜索、读取或编辑任务
5. HTTP 模式：npx @notionhq/notion-mcp-server --transport http

适用场景

1. AI 编程助手读取 Notion 文档：在代码审查时让 AI 直接引用 Notion 产品文档
2. 自动化文档更新：AI 根据代码变更自动更新 Notion 页面，如 Changelog
3. 多工具协同工作流：读取 Notion 任务 -> 创建代码 -> 记录到 Notion
4. 企业知识库查询：构建基于 Notion 的内部知识问答系统
5. 跨工具数据同步：Notion 数据库与 GitHub Issues、Jira 等联动
6. Markdown 博客写作：将 Notion 作为草稿库，AI 读取后发布到其他平台

适用人群

• 使用 Claude Code、Cursor、Windsurf 等 AI 编程工具的开发者
• 将 Notion 作为项目文档或知识库的技术团队
• 需要 AI 辅助进行文档管理和内容更新的个人工作者

工作原理

Notion MCP Server 底层基于 Notion OpenAPI 规范，将每个 Notion API 端点映射为一个 MCP 工具。服务器启动时通过 SDK 自动发现可用工具列表并上报给 MCP 客户端。AI 发送 JSON-RPC 请求后，服务器将参数转发至 Notion API，将响应转换为结构化结果返回。

官方链接

• npm：https://www.npmjs.com/package/@notionhq/notion-mcp-server
• GitHub：https://github.com/makenotion/notion-mcp-server
• 官方文档：https://developers.notion.com/docs/mcp