Notion MCP Server

Notion MCP 服务

面向 AI、适用于 Notion API 的 MCP 服务。它帮助 Agent 查找、阅读、查询和更新 Notion 工作区，同时让响应保持精简，满足日常 AI 工作流的需求。

此服务面向 Notion API 2026-03-11，并采用当前的数据库／数据源模型。它提供 MCP 工具、提示词、资源、结构化工具结果，以及用于交互式 Notion 工作流的可选 MCP Apps。

亮点

• 使用 notion_find 搜索并发现目标。
• 使用 notion_read_page 精简读取页面，并获取稳定的区块 ID。
• 使用 notion_inspect_data_source 检查数据源架构。
• 使用简单值查询数据源，并创建数据源条目。
• 用于编辑页面的简易工具，支持段落、标题、列表、待办事项、引用、标注、代码块、分隔线和安全的 Markdown 追加。
• 用于高级区块、页面、数据库、数据源、评论和用户操作的原始 Notion API 工具。
• 可选 MCP Apps：数据源浏览器和页面工作台。

快速开始

将此服务添加到 Claude Desktop 等 MCP 主机：

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

保存配置后，重启 MCP 主机。

设置指南

1. 创建 Notion 集成

打开 Notion 集成控制面板，然后创建新的内部集成。

2. 配置权限

仅授予所需权限：

• 读取内容：搜索、读取页面、获取数据源和执行查询所必需。
• 插入内容：创建页面／条目和追加区块所必需。
• 更新内容：更新页面、区块和数据源架构所必需。
• 读取评论／插入评论：仅使用评论工具时需要。
• 用户信息：仅使用用户查找工具时需要。

为在设置期间使用全部功能，请启用读取、插入和更新内容的权限。仅在计划使用相关工具时，才添加评论或用户权限。

3. 授予内容访问权限

打开集成的 内容访问 选项卡，然后选择希望 MCP 服务读取或编辑的页面或数据库。

你也可以从目标 Notion 页面或数据库授予访问权限：打开 ... 菜单，选择 连接，然后添加你的集成。

Notion 仅允许集成访问已与其共享的页面和数据库。添加到页面的连接也可以访问该页面的子页面。

4. 复制内部集成令牌

复制集成密钥。此值将在 MCP 主机配置中用作 NOTION_API_TOKEN。

5. 配置 MCP 主机

对于 Cursor、Claude Desktop 和其他 MCP 主机，请将此服务配置添加到 MCP 设置中：

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

对于本地构建的检出版本：

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/absolute/path/to/suekou-mcp-notion-server/build/index.js"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

推荐工作流

1. 使用 notion_find 定位页面或数据源。
2. 使用 notion_read_page 获取页面上下文和可编辑区块 ID。
3. 在查询或创建数据源条目之前，使用 notion_inspect_data_source 检查数据源。
4. 对于常见的数据源操作，使用 notion_query_data_source_by_values 和 notion_create_data_source_item_from_values。
5. 对于常规页面编辑，使用 notion_append_markdown、notion_append_content、notion_update_content 或 notion_update_content_batch。
6. 仅当简化工具不支持所需的 Notion API 数据结构时，才使用原始 JSON 工具。

面向开发者

这些参考资料主要面向开发、自定义和高级 MCP 工作流：

• 配置：环境变量、命令行参数、MCP 主机示例、开发命令和故障排查。
• 工具：按工作流领域分组的完整工具参考。
• 工作流：实用的读取、写入、数据源、迁移和错误处理指南。
• MCP Apps：交互式 Data Source Explorer 和 Page Workbench 详情。

开发

本项目使用 Node.js 22 或更高版本以及 pnpm。

pnpm install --frozen-lockfile
pnpm run build
pnpm test

在本地开发期间使用 MCP inspector：

pnpm run inspector

许可证

此 MCP 服务采用 MIT License 授权。这意味着你可以自由使用、修改和分发该软件，但须遵守 MIT License 的条款和条件。有关详情，请参阅项目仓库中的 LICENSE 文件。