Notion MCP Server：让 AI Agent 无缝操控 Notion 的桥梁

你是否经历过这样的困扰：想用 AI 自动整理 Notion 笔记、建立数据库自动化流程，却发现 Notion 没有原生 AI 接口，一切只能手动操作？或者你是 AI 开发者，想让 Claude 这样的 Agent 直接读写 Notion，却苦于 API 复杂度和 token 限制？

mcp-notion-server 就是来解决这个问题的。它是一个基于 Model Context Protocol（MCP）的 Notion API 服务器，充当 AI Agent 与 Notion 之间的"翻译官"——用 MCP 标准化接口封装 Notion 的所有能力，让任何支持 MCP 的 AI 客户端（Claude Desktop、Cursor、Cline 等）直接操控 Notion 的页面、数据库和内容块。

背景：MCP 生态与 Notion API 的交汇

2024 年底，Anthropic 推出 Model Context Protocol（MCP），意图建立 AI 工具互联的开放标准——类似于 AI 世界的 USB-C 协议。开发者只需实现一次 MCP server，就能让所有 MCP-compatible AI 客户端使用。Notion 官方有 API，但直接集成到 AI workflow 中需要大量胶水代码。mcp-notion-server 的作者 suekou（Kosuke Suenaga）看到了这个 gap，用 TypeScript 完整实现了 Notion MCP server，并在 GitHub 获得 900+ stars，成为 MCP 生态中最受欢迎的 Notion 连接器之一。

项目采用 MIT 许可证，TypeScript 单仓库，代码结构清晰，依赖简洁：核心依赖只有 @modelcontextprotocol/sdk + React 18（用于内置的 MCP Apps UI）。

核心功能：三层工具设计

mcp-notion-server 提供了 三层递进式工具集，这是它与其他 Notion 集成方案最大的不同。

高级工具（推荐优先使用）

这类工具封装了最常见的操作，返回紧凑的结果，适合 AI 工作流：

• notion_find：搜索 Notion 页面和数据库，返回候选列表和稳定 ID，同时附带"建议下一步操作"的元数据——这在 AI Agent 场景下极大减少了工具调用次数。
• notion_read_page：读取页面元数据和子块结构，支持 Markdown、JSON 或紧凑格式输出。通过 stable block ID 避免内容漂移。
• notion_inspect_data_source：检查数据库 schema（属性类型、选项值、关联关系），为后续查询做准备。
• notion_query_data_source_by_values 和 notion_create_data_source_item_from_values：基于 schema 的数据源查询和创建工具，用简单的字段值而非原始 JSON 操作数据库。
• notion_append_content / notion_append_markdown：追加段落、标题、列表、待办事项、引用、代码块、分隔线等常用块，支持直接传 Markdown 文本。
• notion_update_content：更新现有简单块的内容。

MCP Apps（交互式 Web UI）

内置了两个 React 构建的交互式 MCP App，进一步降低了操作门槛：

• Data Source Explorer：图形化数据库结构浏览器，可视化属性、选项和关联关系。
• Page Workbench：页面内容编辑器，支持块级操作预览。

这些 App 通过 MCP 资源（resource）机制暴露，打开后在 MCP host 端渲染为交互界面。

底层原始工具

对于高级工具无法覆盖的场景（如特殊的块类型、自定义属性结构），提供完整的原始 Notion API 工具：

• notion_retrieve_block、notion_append_block_children、notion_update_block、notion_delete_block：块级 CRUD
• notion_search、notion_create_database、notion_update_database：数据库操作
• notion_create_comment、notion_retrieve_comments：评论功能
• notion_retrieve_user、notion_list_all_users：用户查询

所有工具统一支持 format 参数（json 或 markdown）和 response_mode 参数（auto / compact / full），AI 友好。

技术架构：模块化分层设计

项目源码按功能分为清晰的模块：

目录	职责
src/mcp/	MCP 协议层：server.ts 定义所有工具/prompts/resources 注册，result.ts 处理响应格式化
src/notion/	Notion API 封装：client.ts 包装所有 API 调用，含重试（最多2次）、超时控制（30s）、429限流处理
src/tools/	工具实现：按类别分子目录（blocks/content/data-sources/discovery/pages/apps）
src/prompts/	MCP prompts：给 AI 的指令模板，引导合理使用工具链
src/resources/	MCP resources：暴露 Notion 数据为可读资源
src/apps/ui/	MCP Apps 的 React 组件
src/markdown/	Markdown ↔ Notion 块双向转换
src/utils/	工具过滤、参数校验等工具函数

整个服务器通过 StdioServerTransport 以 stdin/stdout 通信运行（MCP 标准协议），适合 Claude Desktop 等本地 MCP host。

部署：轻量快速，但依赖 MCP host

项目没有提供 Dockerfile 或 docker-compose，部署方式完全依赖 MCP 协议标准：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

一行命令即可运行（npx -y @suekou/mcp-notion-server），无需自己编译。要求 Node.js >= 22。

部署流程只需四步：① 在 Notion 创建 internal integration → ② 配置读/写/评论权限 → ③ 将集成连接到目标页面或数据库 → ④ 填入 NOTION_API_TOKEN 即可。整个过程不超过 10 分钟。

无 GPU、无特殊硬件要求，512MB RAM 足够运行。

局限与注意事项

mcp-notion-server 并非完美，以下几点值得注意：

1. Node.js 版本强制要求 >= 22：如果你的环境是较老的 Node 版本，无法运行。
2. 不支持直接 Web 部署：没有 Docker 镜像，不能像普通 Web 服务一样部署在云服务器上，必须作为本地 MCP server 运行。
3. MCP host 强依赖：需要搭配 Claude Desktop、Cursor 等支持 MCP 的 AI 工具使用，单独运行没有 UI。
4. Notion API 版本依赖：项目使用 Notion API 2026-03-11，如果 Notion API 有重大变更需要同步更新。
5. 中文 Notion 页面处理：项目默认 Markdown 转换对中文支持依赖 NOTION_MARKDOWN_CONVERSION=true 环境变量开启，否则全走 JSON。

行业意义

mcp-notion-server 的出现代表了 AI Agent 工具生态的一个典型路径：围绕 MCP 协议，把垂类 API 包装成 AI-native 工具。它不是第一个 MCP Notion 集成，但三层工具设计（高级工具 → Apps → 原始 API）让它成为目前最实用的选择。

随着 MCP 生态持续扩张，这类"协议适配器"类项目会越来越多——它们的价值在于降低 AI 与现有 SaaS 工具集成的认知和开发成本，让开发者专注于 AI workflow 本身而非 API 细节。mcp-notion-server 作为其中的代表性项目，值得 AI 工具开发者关注和实践。