AI导哈

Notion API服务器

一个为Notion API设计的MCP服务器，使LLM能够与Notion工作区交互，并通过Markdown转换优化令牌使用。

  • by kimjungyeol
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 kimjungyeol/mcp-notion-server

使用说明

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

  1. 创建概念集成:

    • 访问 注意您的集成页面.
    • 单击“新建集成”。
    • 命名您的集成并选择适当的权限（例如，“读取内容”、“更新内容”）。

  2. 检索密钥:

    • 从您的集成中复制“内部集成令牌”。
    • 此令牌将用于身份验证。

  3. 将集成添加到工作区:

    • 在Notion中打开要集成访问的页面或数据库。
    • 点击右上角的“···”按钮。
    • 单击“连接”按钮，然后选择您在上述步骤1中创建的集成。

  4. 配置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" 当您需要修改返回的内容时

故障排除

如果遇到权限错误：

  1. 确保集成具有所需的权限。
  2. 验证是否邀请集成到相关页面或数据库。
  3. 确认令牌和配置已正确设置 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”。

  1. notion_append_block_children

    • 将子块附加到父块。
    • 所需输入：
      • block_id （string）：父块的ID。
      • children （array）：要附加的块对象数组。
    • 返回：有关附加块的信息。

  2. notion_retrieve_block

    • 检索特定块的信息。
    • 所需输入：
      • block_id （string）：要检索的块的ID。
    • 返回：有关块的详细信息。

  3. notion_retrieve_block_children

    • 检索特定块的子对象。
    • 所需输入：
      • block_id （string）：父块的ID。
    • 可选输入：
      • start_cursor （string）：下一页结果的光标。
      • page_size （数字，默认值：100，最大值：100）：要检索的块数。
    • 返回：子块列表。

  4. notion_delete_block

    • 删除特定块。
    • 所需输入：
      • block_id （string）：要删除的块的ID。
    • 返回：确认删除。

  5. notion_retrieve_page

    • 检索特定页面的信息。
    • 所需输入：
      • page_id （string）：要检索的页面的ID。
    • 返回：关于页面的详细信息。

  6. notion_update_page_properties

    • 更新页面的属性。
    • 所需输入：
      • page_id （string）：要更新的页面的ID。
      • properties （对象）：要更新的属性。
    • 返回：有关更新页面的信息。

  7. notion_create_database

    • 创建新数据库。
    • 所需输入：
      • parent （object）：数据库的父对象。
      • properties （object）：数据库的属性架构。
    • 可选输入：
      • title （array）：作为富文本数组的数据库标题。
    • 返回：有关创建的数据库的信息。

  8. notion_query_database

    • 查询数据库。
    • 所需输入：
      • database_id （string）：要查询的数据库的ID。
    • 可选输入：
      • filter （object）：过滤条件。
      • sorts （array）：排序条件。
      • start_cursor （string）：下一页结果的光标。
      • page_size （数字，默认值：100，最大值：100）：要检索的结果数。
    • 返回：查询结果列表。

  9. notion_retrieve_database

    • 检索特定数据库的信息。
    • 所需输入：
      • database_id （string）：要检索的数据库的ID。
    • 返回：有关数据库的详细信息。

  10. notion_update_database

    • 更新有关数据库的信息。
    • 所需输入：
      • database_id （string）：要更新的数据库的ID。
    • 可选输入：
      • title （array）：数据库的新标题。
      • description （array）：数据库的新描述。
      • properties （对象）：已更新属性架构。
    • 返回：有关已更新数据库的信息。

  11. notion_create_database_item

    • 在Notion数据库中创建新项目。
    • 所需输入：
      • database_id （string）：要将项目添加到的数据库的ID。
      • properties （object）：新项目的属性。这些应该与数据库架构匹配。
    • 返回：有关新创建项目的信息。

  12. notion_search

    • 按标题搜索页面或数据库。
    • 可选输入：
      • query （string）：在页面或数据库标题中搜索的文本。
      • filter （object）：将结果限制为仅页面或仅数据库的标准。
      • sort （object）：对结果进行排序的标准
      • start_cursor （string）：分页开始光标。
      • page_size （数字，默认值：100，最大值：100）：要检索的结果数。
    • 返回：匹配页面或数据库的列表。

  13. notion_list_all_users

    • 列出Notion工作区中的所有用户。
    • 注意：此功能需要升级到Notion Enterprise计划，并使用组织API密钥以避免权限错误。
    • 可选输入：
      • start_cursor（字符串）：用于列出用户的分页开始光标。
      • page_size（number，max:100）：要检索的用户数。
    • 返回：工作区中所有用户的分页列表。

  14. notion_retrieve_user

    • 通过Notion中的user_id检索特定用户。
    • 注意：此功能需要升级到Notion Enterprise计划，并使用组织API密钥以避免权限错误。
    • 所需输入：
      • user_id（string）：要检索的用户的id。
    • 返回：指定用户的详细信息。

  15. notion_retrieve_bot_user

    • 在Notion中检索与当前令牌关联的机器人用户。
    • 返回：有关机器人用户的信息，包括授权集成的人员的详细信息。

  16. notion_create_comment

    • 在Notion中创建评论。
    • 要求集成具有“插入注释”功能。
    • 指定一个 parent 带有a的对象 page_id 或a discussion_id但不是两者都有。
    • 所需输入：
      • rich_text （array）：表示评论内容的富格文本对象数组。
    • 可选输入：
      • parent （对象）：必须包括 page_id 如果使用。
      • discussion_id （string）：现有讨论线程ID。
    • 返回：关于已创建评论的信息。

  17. notion_retrieve_comments

    • 从Notion页面或块中检索未解决的注释列表。
    • 要求集成具有“读取注释”功能。
    • 所需输入：
      • block_id （string）：要检索其注释的块或页面的ID。
    • 可选输入：
      • start_cursor （string）：分页开始光标。
      • page_size （number，max:100）：要检索的评论数。
    • 返回：与指定块或页面关联的注释的分页列表。

许可证

此MCP服务器根据MIT许可证获得许可。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发软件。有关更多详细信息，请参阅项目存储库中的LICENSE文件。

相关 MCP