Not MCP 服务器

用于 Notion API 的 MCP 服务器，使 LLM 能够与 Notion 工作区交互。此外，它采用 Markdown 转换来减少与 LLM 通信时的上下文大小，从而优化 token 使用并提高交互效率。

设置

以下文章对上述步骤进行了详细解释：

• 英文版本： https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h

• 日文版： https://qiita.com/suekou/items/44c864583f5e3e6325d9

1. 创建概念集成：

   • 访问Notion 您的集成页面。

   • 点击“新集成”。

   • 命名您的集成并选择适当的权限（例如，“阅读内容”，“更新内容”）。

2. 检索密钥：

   • 从您的集成中复制“内部集成令牌”。

   • 该令牌将用于身份验证。

3. 将集成添加到您的工作区：

   • 在 Notion 中打开您希望集成访问的页面或数据库。

   • 点击右上角的“···”按钮。

   • 单击“连接”按钮，然后选择您在上面的步骤 1 中创建的集成。

4. 配置 Claude Desktop ：将以下内容添加到您的claude_desktop_config.json中：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/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"
      }
    }
  }
}

Related MCP server: MCP Notion Server (@suncreation)

环境变量

• NOTION_API_TOKEN （必需）：您的 Notion API 集成令牌。

• NOTION_MARKDOWN_CONVERSION ：设置为“true”以启用实验性的 Markdown 转换。这可以显著减少浏览内容时的 token 消耗，但在编辑页面内容时可能会出现问题。

命令行参数

• --enabledTools ：以逗号分隔的要启用的工具列表（例如“notion_retrieve_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", "@suekou/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"时），使其更易于阅读，并显著减少 token 消耗。但是，由于此功能尚处于实验阶段，因此在尝试编辑页面内容时可能会出现问题，因为原始结构会在转换过程中丢失。

您可以通过在工具调用中将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 ：应用程序入口点。解析命令行参数并启动服务器。

• client/ ：负责与 Notion API 通信的模块。

  • index.ts ：NotionClientWrapper 类实现所有 API 调用。

• server/ ：MCP 服务器实现。

  • index.ts ：处理从 Claude 收到的请求并调用适当的客户端方法。

• types/ ：类型定义模块。

  • index.ts ：导出所有类型。

  • args.ts ：工具参数的接口定义。

  • common.ts ：常见模式的定义（ID 格式、富文本等）。

  • responses.ts ：Notion API 响应的类型定义。

  • schemas.ts ：MCP 工具模式的定义。

• utils/ ：实用程序功能。

  • index.ts ：类似过滤启用工具的功能。

• markdown/ ：Markdown 转换功能。

  • index.ts ：将 JSON 响应转换为 Markdown 格式的逻辑。

工具

所有工具都支持以下可选参数：

• format （字符串，“json” 或 “markdown”，默认值：“markdown”）：控制响应格式。使用“markdown”表示人类可读的输出，“json”表示以编程方式访问原始数据结构。注意：仅当NOTION_MARKDOWN_CONVERSION环境变量设置为“true”时，Markdown 转换才有效。

1. notion_append_block_children

   • 将子块附加到父块。

   • 必需输入：

     • block_id （字符串）：父块的 ID。

     • children （数组）：要附加的块对象数组。

   • 返回：有关附加块的信息。

2. notion_retrieve_block

   • 检索有关特定块的信息。

   • 必需输入：

     • block_id （字符串）：要检索的块的 ID。

   • 返回：有关该块的详细信息。

3. notion_retrieve_block_children

   • 检索特定块的子块。

   • 必需输入：

     • block_id （字符串）：父块的 ID。

   • 可选输入：

     • start_cursor （字符串）：下一页结果的光标。

     • page_size （数字，默认值：100，最大值：100）：要检索的块数。

   • 返回：子块列表。

4. notion_delete_block

   • 删除特定块。

   • 必需输入：

     • block_id （字符串）：要删除的块的 ID。

   • 返回：删除确认。

5. notion_retrieve_page

   • 检索有关特定页面的信息。

   • 必需输入：

     • page_id （字符串）：要检索的页面的 ID。

   • 返回：有关页面的详细信息。

6. notion_update_page_properties

   • 更新页面的属性。

   • 必需输入：

     • page_id （字符串）：要更新的页面的 ID。

     • properties （对象）：要更新的属性。

   • 返回：有关更新页面的信息。

7. notion_create_database

   • 创建一个新的数据库。

   • 必需输入：

     • parent （对象）：数据库的父对象。

     • properties （对象）：数据库的属性模式。

   • 可选输入：

     • title （数组）：数据库的标题作为富文本数组。

   • 返回：有关创建的数据库的信息。

8. notion_query_database

   • 查询数据库。

   • 必需输入：

     • database_id （字符串）：要查询的数据库的 ID。

   • 可选输入：

     • filter （对象）：过滤条件。

     • sorts （数组）：排序条件。

     • start_cursor （字符串）：下一页结果的光标。

     • page_size （数字，默认值：100，最大值：100）：要检索的结果数。

   • 返回：查询结果列表。

9. notion_retrieve_database

   • 检索有关特定数据库的信息。

   • 必需输入：

     • database_id （字符串）：要检索的数据库的 ID。

   • 返回：有关数据库的详细信息。

10. notion_update_database

• 更新有关数据库的信息。

• 必需输入：

  • database_id （字符串）：要更新的数据库的 ID。

• 可选输入：

  • title （数组）：数据库的新标题。

  • description （数组）：数据库的新描述。

  • properties （对象）：更新的属性模式。

• 返回：有关更新数据库的信息。

11. notion_create_database_item

• 在 Notion 数据库中创建一个新项目。

• 必需输入：

  • database_id （字符串）：要添加项目的数据库的 ID。

  • properties （对象）：新项目的属性。这些属性应与数据库架构匹配。

• 返回：有关新创建项目的信息。

12. notion_search

• 按标题搜索页面或数据库。

• 可选输入：

  • query （字符串）：在页面或数据库标题中搜索的文本。

  • filter （对象）：将结果限制为仅页面或仅数据库的标准。

  • sort （对象）：对结果进行排序的标准

  • start_cursor （字符串）：分页起始光标。

  • page_size （数字，默认值：100，最大值：100）：要检索的结果数。

• 返回：匹配的页面或数据库的列表。

13. notion_list_all_users

• 列出 Notion 工作区中的所有用户。

• 注意：此功能需要升级到 Notion Enterprise 计划并使用组织 API 密钥以避免权限错误。

• 可选输入：

  • start_cursor（字符串）：用于列出用户的分页起始光标。

  • page_size（数字，最大值：100）：要检索的用户数量。

• 返回：工作区中所有用户的分页列表。

14. notion_retrieve_user

• 在 Notion 中通过 user_id 检索特定用户。

• 注意：此功能需要升级到 Notion Enterprise 计划并使用组织 API 密钥以避免权限错误。

• 必需输入：

  • user_id（字符串）：要检索的用户的 ID。

• 返回：有关指定用户的详细信息。

15. notion_retrieve_bot_user

• 在 Notion 中检索与当前令牌关联的机器人用户。

• 返回：有关机器人用户的信息，包括授权集成的人员的详细信息。

16. notion_create_comment

• 在 Notion 中创建评论。

• 要求集成具有“插入评论”功能。

• 使用page_id或discussion_id指定parent对象，但不能同时使用两者。

• 必需输入：

  • rich_text （数组）：表示评论内容的富文本对象数组。

• 可选输入：

  • parent （对象）：如果使用，必须包含page_id 。

  • discussion_id （字符串）：现有的讨论线程 ID。

• 返回：有关创建的评论的信息。

17. notion_retrieve_comments

• 从 Notion 页面或块中检索未解决的评论列表。

• 要求集成具有“阅读评论”功能。

• 必需输入：

  • block_id （字符串）：您要检索其评论的块或页面的 ID。

• 可选输入：

  • start_cursor （字符串）：分页起始光标。

  • page_size （数字，最大值：100）：要检索的评论数量。

• 返回：与指定块或页面相关的评论的分页列表。

执照

此 MCP 服务器采用 MIT 许可证。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。更多详情，请参阅项目仓库中的 LICENSE 文件。