Notion ReadOnly MCP Server

Notion ReadOnly MCP 服务

本项目为 Notion API 实现了一个经过优化的只读 MCP 服务，专注于性能和效率，便于 AI 助手查询和检索 Notion 内容。

主要改进

• 只读设计：专注于数据检索操作，确保安全地访问 Notion 内容。
• 精简工具集：将公开的 Notion API 工具数量从 15 个以上减少到仅 6 个文档分析必备工具。
• 并行处理：通过实现异步并行 API 请求来检索区块内容，显著缩短响应时间，提升性能。
• 扩展数据库访问：新增对数据库、页面属性和评论检索操作的支持。
• 针对 AI 助手优化：大幅减少工具数量，解决 Cursor 等 AI 助手中的“工具过多会降低性能”问题。这些助手通常将模型可用工具数限制在约 40 个。

工具对比

与标准 Notion API 集成相比，此只读实现公开的工具数量少得多，从而提升性能并增强与 AI 助手的兼容性：

精简后的工具集有助于将工具数量控制在建议范围内，从而优化 AI 助手的性能，同时仍提供所有必要功能。

安装

1. 在 Notion 中设置集成：

访问 https://www.notion.so/profile/integrations 并创建新的内部集成，或选择现有集成。

虽然我们将 Notion API 的公开范围限制为只读操作，但向大模型公开数据仍存在非零的工作区数据风险。注重安全的用户可以进一步配置集成的 Capabilities。

例如，你可以在“Configuration”选项卡中仅授予“Read content”权限，以创建只读集成令牌：

2. 将 MCP 配置添加到客户端：

使用 npm：

将以下内容添加到 .cursor/mcp.json 或 claude_desktop_config.json（MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json）

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "notion-readonly-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2022-06-28\" }"
      }
    }
  }
}

使用 Docker：

将以下内容添加到 .cursor/mcp.json 或 claude_desktop_config.json：

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "OPENAPI_MCP_HEADERS",
        "taewoong1378/notion-readonly-mcp-server"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

别忘了将 ntn_**** 替换为你的集成密钥。可在集成配置选项卡中找到该密钥。

3. 将内容连接到集成：

确保将相关页面和数据库连接到你的集成。

为此，请访问相应页面，点击 3 个点，然后选择“Connect to integration”。

可用工具

此优化后的服务仅公开必要的只读 Notion API 工具：

• API-retrieve-a-page：获取页面信息
• API-get-block-children：获取页面内容块（支持并行处理）
• API-retrieve-a-block：获取特定块的详细信息
• API-retrieve-a-database：获取数据库信息
• API-retrieve-a-comment：获取页面或块上的评论
• API-retrieve-a-page-property：获取页面中特定属性的信息
• API-get-one-pager：新功能！ 通过单次调用递归获取完整的 Notion 页面及其所有内容块、数据库和相关内容

通过将工具限制为这 7 个必要工具（标准实现中有 15 个以上），我们可以确保：

1. 提升 Cursor 和 Claude 等受工具数量限制的 AI 助手的性能
2. 减轻 AI 模型在选择合适工具时的认知负担
3. 减少需要考虑的 API 选项，从而加快响应速度
4. 通过缩小 API 接口范围来增强安全性

自动内容探索

新的 API-get-one-pager 工具提供了一种强大的方式来探索 Notion 页面，无需多次调用 API：

• 递归获取：自动遍历整个页面结构，包括嵌套块
• 并行处理：同时获取多个块及其子块，以实现最高性能
• 智能缓存：存储获取的数据，尽量减少重复的 API 调用
• 全面的内容：包含页面、块、数据库、评论和详细的属性信息
• 可自定义深度：控制递归层级，在详细程度和性能之间取得平衡

使用 One Pager 工具

{
  "page_id": "YOUR_PAGE_ID",
  "maxDepth": 5,               // Optional: Maximum recursion depth (default: 5)
  "includeDatabases": true,    // Optional: Include linked databases (default: true)
  "includeComments": true,     // Optional: Include comments (default: true)
  "includeProperties": true    // Optional: Include detailed page properties (default: true)
}

对于需要了解 Notion 页面全部内容的 AI 助手而言，这种自动探索功能尤其有用。它无需进行数十次单独的 API 调用，因此能提供更快、更高效的响应。

异步处理

此服务采用先进的并行处理技术来处理大型 Notion 文档：

• 将多个请求批量处理并发执行
• 自动处理内容块子项的分页
• 返回结果前高效汇总数据
• 通过控制台日志展示处理过程，且不影响响应格式

示例

1. 使用以下指令：

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

AI 将通过并行处理内容块，高效获取页面详情。

2. 使用数据库信息：

Get the structure of database 8a6b35e6e67f802fa7e1d27686f017f2

开发

构建：

pnpm build

执行：

pnpm dev

许可证

MIT

AI 助手性能优势

Cursor 和 Claude 等现代 AI 助手在可有效处理的工具数量方面存在限制：

• 大多数模型可能无法遵循总数超过 40 个工具的配置
• 工具过多会降低整体性能和推理能力
• 复杂的工具集会增加响应延迟和决策难度

此只读实现刻意缩小了 Notion API 接口范围，以应对这些限制，同时保留所有必要功能。这样可以实现：

• AI 助手响应更快、更可靠
• 与 Notion 内容交互时准确性更高
• 通过专注的 API 设计提升整体性能