Notion MCP Server

面向 AI 的 Notion API MCP 服务器。它帮助智能体查找、读取、查询和更新 Notion 工作区，同时保持响应足够紧凑，适合日常 AI 工作流。

该服务器针对 Notion API 2026-03-11 版本，并使用当前的数据库/数据源模型。它提供 MCP 工具、提示词、资源、结构化工具结果，以及可选的 MCP Apps，用于交互式 Notion 工作流。

亮点

• 通过 notion_find 进行搜索和目标发现。
• 通过 notion_read_page 以稳定的块 ID 进行紧凑的页面读取。
• 通过 notion_inspect_data_source 检查数据源模式。
• 支持模式感知的数据源查询和简单值创建条目。
• 简单的页面编辑工具，支持段落、标题、列表、待办事项、引用、提示框、代码块、分割线以及安全的 Markdown 追加。
• 原始 Notion API 工具，用于高级块、页面、数据库、数据源、评论和用户操作。
• 可选的 MCP Apps：数据源浏览器（Data Source Explorer）和页面工作台（Page Workbench）。

快速开始

将此服务器添加到 MCP 主机（如 Claude Desktop）：

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

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

设置指南

1. 创建 Notion 集成

打开 Notion 集成仪表盘，然后创建一个新的内部集成。

2. 配置能力

只授予你需要的权限：

• 读取内容：搜索、页面读取、数据源检索和查询所必需。
• 插入内容：创建页面/条目和追加块所必需。
• 更新内容：更新页面、块和数据源模式所必需。
• 读取评论 / 插入评论：仅在需要评论工具时使用。
• 用户信息：仅在需要用户查找工具时使用。

为了在设置期间获得完整功能，请启用读取、插入和更新内容。只有在你计划使用这些工具时，才添加评论或用户权限。

3. 授予内容访问权限

打开你的集成的 内容访问（Content access） 标签页，然后选择希望 MCP 服务器读取或编辑的页面或数据库。

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

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：交互式数据源浏览器和页面工作台的详细信息。

开发

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

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

使用 MCP inspector …