Notion 只读 MCP 服务器

该项目实现了一个针对 Notion API 的优化只读 MCP 服务器，专注于性能和效率，以便 AI 助手可以查询和检索 Notion 内容。

主要改进

只读设计：仅专注于数据检索操作，确保安全访问 Notion 内容。
最小化工具集：将暴露的 Notion API 工具数量从 15 个以上减少到只有 6 个用于文档分析的基本工具。
并行处理：通过实现异步和并行 API 请求来检索块内容，显著提高了性能，大幅减少了响应时间。
扩展数据库访问：增加了对数据库、页面属性和评论检索操作的支持。
针对 AI 助手优化：显著减少工具数量解决了“过多工具会降低性能”的问题，这在像 Cursor 这样的 AI 助手中尤为重要，这些助手通常限制模型使用大约 40 个工具。

工具对比

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

Notion API 工具对比

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

安装

1. 在 Notion 中设置集成：

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

创建 Notion 集成令牌

虽然我们将 Notion API 的范围限制为只读操作，但将工作区数据暴露给 LLMs 仍存在非零风险。注重安全性的用户可能希望进一步配置集成的功能。

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

Notion 集成令牌功能显示已选中读取内容

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

使用 npm：

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

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：

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. 将内容连接到集成：

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

为此，请访问该页面，点击三个点，然后选择“连接到集成”。

将集成令牌添加到 Notion 连接

可用工具

此优化服务器仅暴露必需的只读 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个以上），我们确保了：

在像Cursor和Claude这样的AI助手中有更好的性能，这些助手对工具数量有限制
减少了AI模型在选择合适工具时的认知负担
由于需要考虑的API选项较少，响应时间更快
通过最小化API表面积增强了安全性

自动内容探索

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

递归检索：自动遍历整个页面结构，包括嵌套块
并行处理：同时获取多个块及其子块以达到最大性能
智能缓存：存储检索到的数据以减少冗余的API调用
全面的内容：包括页面、块、数据库、评论以及详细的属性信息
可定制的深度：控制递归级别以平衡细节与性能

使用One Pager工具

{ "page_id": "YOUR_PAGE_ID", "maxDepth": 5, // 可选：最大递归深度（默认值：5） "includeDatabases": true, // 可选：包含链接的数据库（默认值：true） "includeComments": true, // 可选：包含评论（默认值：true） "includeProperties": true // 可选：包含详细的页面属性（默认值：true） }

这种自动探索能力对于需要理解整个Notion页面内容而不必进行数十次单独API调用的AI助手特别有用，从而大大提高了响应速度和效率。

异步处理

服务器实现了先进的并行处理技术来处理大型Notion文档：

多个请求被批量并发处理
块子项的分页处理是自动的
结果在返回前被高效聚合
控制台日志提供了过程可见性，而不影响响应格式

示例

使用以下指令：

获取页面1a6b35e6e67f802fa7e1d27686f017f2的内容

AI将通过并行处理块内容的方式高效地检索页面详情。

使用数据库信息：

获取数据库8a6b35e6e67f802fa7e1d27686f017f2的结构

开发

构建：

pnpm build

执行：

pnpm dev

许可证

MIT

AI助手性能优势

现代AI助手如Cursor和Claude在能够有效处理的工具数量上有限制：

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

这个只读实现有意减少了Notion API的表面积，以解决这些限制，同时保留了所有必要的功能。结果是：

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

来源

来源：github
链接：https://github.com/taewoong1378/notion-readonly-mcp-server

Taewoong1378