Notion ReadOnly MCP

注意只读MCP服务器

该项目为Notion API实现了一个优化的只读MCP服务器，重点关注AI助手查询和检索Notion内容的性能和效率。

关键改进

• 只读设计：专注于数据检索操作，确保安全访问Notion内容。
• 最小化工具集：将公开的Notion API工具的数量从15+减少到只有6个用于文档分析的基本工具。
• 并行处理：通过实现用于检索块内容的异步和并行API请求，大大缩短了响应时间，从而增强了性能。
• 扩展数据库访问：添加了对数据库、页面属性和注释检索操作的支持。
• 针对AI助手进行了优化：大幅减少工具数量解决了Cursor等人工智能助手中的“工具太多会降低性能”问题，该问题将模型限制在大约40个工具。

工具比较

与标准的Notion API集成相比，这种只读实现暴露的工具要少得多，从而提高了性能和与AI助手的兼容性：

Notion API Tools Comparison

减少的工具集有助于保持在推荐的工具限制范围内，以获得最佳的AI助手性能，同时仍然提供所有基本功能。

安装

1.在理念上建立一体化：

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

Creating a Notion Integration token

虽然我们限制了Notion API暴露于只读操作的范围，但通过将其暴露于LLM，工作空间数据存在非零风险。有安全意识的用户可能希望进一步配置集成 _能力_.

例如，您可以通过仅从“配置”选项卡授予“读取内容”访问权限来创建只读集成令牌：

Notion Integration Token Capabilities showing Read content checked

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个点，然后选择“连接到集成”。

Adding Integration Token to Notion Connections

可用工具

此优化的服务器仅公开重要的只读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调用
• 内容全面：包括页面、块、数据库、评论和详细的房产信息
• 可定制深度：控制递归级别，以在细节和性能之间取得平衡

使用一个分页工具

{
  "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页面的整个内容而无需进行数十次单独的API调用的人工智能助手尤其有用，从而获得更快、更高效的响应。

异步处理

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

• 多个请求被批处理并同时处理
• 对阻塞儿童自动处理分页
• 结果在返回之前被有效地聚合
• 控制台日志记录提供了对流程的可见性，而不会影响响应格式

例子

1. 使用以下说明：

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

人工智能将通过并行处理块内容高效地检索页面详细信息。

1. 使用数据库信息：

Get the structure of database 8a6b35e6e67f802fa7e1d27686f017f2

发展

构建：

pnpm build

执行：

pnpm dev

许可证

麻省理工学院

AI助手性能优势

像Cursor和Claude这样的现代人工智能助手在可以有效处理的工具数量上存在局限性：

• 大多数型号可能总共不超过40个工具
• 太多的工具会降低整体性能和推理能力
• 复杂的工具集增加了响应延迟和决策难度

这种只读实现有意减少Notion API表面，以解决这些限制，同时保留所有基本功能。结果是：

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