MCP服务器概念
用于Notion API的MCP服务器，使LLM能够与Notion工作空间交互。此外，它采用Markdown转换来减少与LLM通信时的上下文大小，优化令牌使用并提高交互效率。
设置
以下是对以下文章中提到的步骤的详细解释：
- 英文版本：https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h
- 日文版本：https://qiita.com/suekou/items/44c864583f5e3e6325d9
- 创建概念集成:
- 访问 注意您的集成页面. - 单击“新建集成”。 - 命名您的集成并选择适当的权限（例如，“读取内容”、“更新内容”）。
- 检索密钥:
- 从您的集成中复制“内部集成令牌”。 - 此令牌将用于身份验证。
- 将集成添加到工作区:
- 在Notion中打开要集成访问的页面或数据库。 - 点击右上角的“···”按钮。 - 单击“连接”按钮，然后选择您在上述步骤1中创建的集成。
- 配置Claude桌面:
将以下内容添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@kimjungyeol/mcp-notion-server"],
"env": {
"NOTION_API_TOKEN": "your-integration-token"
}
}
}
}或
{
"mcpServers": {
"notion": {
"command": "node",
"args": ["your-built-file-path"],
"env": {
"NOTION_API_TOKEN": "your-integration-token"
}
}
}
}环境变量
NOTION_API_TOKEN（必需）：您的Notion API集成令牌。NOTION_MARKDOWN_CONVERSION：设置为“true”以启用实验性Markdown转换。这可以显著减少查看内容时的令牌消耗，但在尝试编辑页面内容时可能会导致问题。
命令行参数
--enabledTools：以逗号分隔的要启用的工具列表（例如“notion_receive_page，notion_query_database”）。指定后，只有列出的工具可用。如果未指定，则启用所有工具。
只读工具示例（复制粘贴友好）：
node build/index.js --enabledTools=notion_retrieve_block,notion_retrieve_block_children,notion_retrieve_page,notion_query_database,notion_retrieve_database,notion_search,notion_list_all_users,notion_retrieve_user,notion_retrieve_bot_user,notion_retrieve_comments高级配置
Markdown转换
默认情况下，所有响应都以JSON格式返回。您可以启用实验性的Markdown转换来减少代币消耗：
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@kimjungyeol/mcp-notion-server"],
"env": {
"NOTION_API_TOKEN": "your-integration-token",
"NOTION_MARKDOWN_CONVERSION": "true"
}
}
}
}或
{
"mcpServers": {
"notion": {
"command": "node",
"args": ["your-built-file-path"],
"env": {
"NOTION_API_TOKEN": "your-integration-token",
"NOTION_MARKDOWN_CONVERSION": "true"
}
}
}
}当 NOTION_MARKDOWN_CONVERSION 设置为 "true"，响应将转换为Markdown格式（当 format 参数设置为 "markdown")使其更易于人类阅读，并显著减少代币消耗。然而，由于此功能是实验性的，因此在尝试编辑页面内容时可能会出现问题，因为原始结构在转换过程中会丢失。
您可以通过设置 format 参数为 "json" 或 "markdown" 在您的工具调用中：
- 使用
"markdown"仅查看内容时具有更好的可读性 - 使用
"json"当您需要修改返回的内容时
故障排除
如果遇到权限错误：
- 确保集成具有所需的权限。
- 验证是否邀请集成到相关页面或数据库。
- 确认令牌和配置已正确设置
claude_desktop_config.json.
项目结构
该项目以模块化的方式组织，以提高可维护性和可读性：
./
├── src/
│ ├── index.ts # Entry point and command-line handling
│ ├── client/
│ │ └── index.ts # NotionClientWrapper class for API interactions
│ ├── server/
│ │ └── index.ts # MCP server setup and request handling
│ ├── types/
│ │ ├── index.ts # Type exports
│ │ ├── args.ts # Tool argument interfaces
│ │ ├── common.ts # Common schema definitions
│ │ ├── responses.ts # API response type definitions
│ │ └── schemas.ts # Tool schema definitions
│ ├── utils/
│ │ └── index.ts # Utility functions
│ └── markdown/
│ └── index.ts # Markdown conversion utilities目录说明
- index.ts：应用程序入口点。解析命令行参数并启动服务器。
- 客户/：负责与Notion API通信的模块。
- index.ts：NotionClientWrapper类实现所有API调用。
- 服务器/：MCP服务器实现。
- index.ts：处理从Claude收到的请求，并调用适当的客户端方法。
- 类型/：类型定义模块。
- index.ts：所有类型的导出。 - args.ts：工具参数的接口定义。 - common.ts：常见模式的定义（ID格式、富文本等）。 - responses.ts：Notion API响应的类型定义。 - schemas.ts：MCP工具模式的定义。
- 有用/：实用功能。
- index.ts：启用过滤功能的工具等功能。
- 降价/：Markdown转换功能。
- index.ts：将JSON响应转换为Markdown格式的逻辑。
工具
所有工具都支持以下可选参数：
format（字符串，“json”或“markdown”，默认值：“markdown“）：控制响应格式。使用“markdown”进行人类可读的输出，使用“json”进行对原始数据结构的编程访问。注意：Markdown转换仅在以下情况下有效NOTION_MARKDOWN_CONVERSION环境变量设置为“true”。
notion_append_block_children
- 将子块附加到父块。 - 所需输入： - block_id （string）：父块的ID。 - children （array）：要附加的块对象数组。 - 返回：有关附加块的信息。
notion_retrieve_block
- 检索特定块的信息。 - 所需输入： - block_id （string）：要检索的块的ID。 - 返回：有关块的详细信息。
notion_retrieve_block_children
- 检索特定块的子对象。 - 所需输入： - block_id （string）：父块的ID。 - 可选输入： - start_cursor （string）：下一页结果的光标。 - page_size （数字，默认值：100，最大值：100）：要检索的块数。 - 返回：子块列表。
notion_delete_block
- 删除特定块。 - 所需输入： - block_id （string）：要删除的块的ID。 - 返回：确认删除。
notion_retrieve_page
- 检索特定页面的信息。 - 所需输入： - page_id （string）：要检索的页面的ID。 - 返回：关于页面的详细信息。
notion_update_page_properties
- 更新页面的属性。 - 所需输入： - page_id （string）：要更新的页面的ID。 - properties （对象）：要更新的属性。 - 返回：有关更新页面的信息。
notion_create_database
- 创建新数据库。 - 所需输入： - parent （object）：数据库的父对象。 - properties （object）：数据库的属性架构。 - 可选输入： - title （array）：作为富文本数组的数据库标题。 - 返回：有关创建的数据库的信息。
notion_query_database
- 查询数据库。 - 所需输入： - database_id （string）：要查询的数据库的ID。 - 可选输入： - filter （object）：过滤条件。 - sorts （array）：排序条件。 - start_cursor （string）：下一页结果的光标。 - page_size （数字，默认值：100，最大值：100）：要检索的结果数。 - 返回：查询结果列表。
notion_retrieve_database
- 检索特定数据库的信息。 - 所需输入： - database_id （string）：要检索的数据库的ID。 - 返回：有关数据库的详细信息。
notion_update_database
- 更新有关数据库的信息。 - 所需输入： - database_id （string）：要更新的数据库的ID。 - 可选输入： - title （array）：数据库的新标题。 - description （array）：数据库的新描述。 - properties （对象）：已更新属性架构。 - 返回：有关已更新数据库的信息。
notion_create_database_item
- 在Notion数据库中创建新项目。 - 所需输入： - database_id （string）：要将项目添加到的数据库的ID。 - properties （object）：新项目的属性。这些应该与数据库架构匹配。 - 返回：有关新创建项目的信息。
notion_search
- 按标题搜索页面或数据库。 - 可选输入： - query （string）：在页面或数据库标题中搜索的文本。 - filter （object）：将结果限制为仅页面或仅数据库的标准。 - sort （object）：对结果进行排序的标准 - start_cursor （string）：分页开始光标。 - page_size （数字，默认值：100，最大值：100）：要检索的结果数。 - 返回：匹配页面或数据库的列表。
notion_list_all_users
- 列出Notion工作区中的所有用户。 - 注意：此功能需要升级到Notion Enterprise计划，并使用组织API密钥以避免权限错误。 - 可选输入： - start_cursor（字符串）：用于列出用户的分页开始光标。 - page_size（number，max:100）：要检索的用户数。 - 返回：工作区中所有用户的分页列表。
notion_retrieve_user
- 通过Notion中的user_id检索特定用户。 - 注意：此功能需要升级到Notion Enterprise计划，并使用组织API密钥以避免权限错误。 - 所需输入： - user_id（string）：要检索的用户的id。 - 返回：指定用户的详细信息。
notion_retrieve_bot_user
- 在Notion中检索与当前令牌关联的机器人用户。 - 返回：有关机器人用户的信息，包括授权集成的人员的详细信息。
notion_create_comment
- 在Notion中创建评论。 - 要求集成具有“插入注释”功能。 - 指定一个 parent 带有a的对象 page_id 或a discussion_id但不是两者都有。 - 所需输入： - rich_text （array）：表示评论内容的富格文本对象数组。 - 可选输入： - parent （对象）：必须包括 page_id 如果使用。 - discussion_id （string）：现有讨论线程ID。 - 返回：关于已创建评论的信息。
notion_retrieve_comments
- 从Notion页面或块中检索未解决的注释列表。 - 要求集成具有“读取注释”功能。 - 所需输入： - block_id （string）：要检索其注释的块或页面的ID。 - 可选输入： - start_cursor （string）：分页开始光标。 - page_size （number，max:100）：要检索的评论数。 - 返回：与指定块或页面关联的注释的分页列表。
许可证
此MCP服务器根据MIT许可证获得许可。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发软件。有关更多详细信息，请参阅项目存储库中的LICENSE文件。