Notion MCP 服务器

用于 Notion API 的 MCP 服务器，使 Claude 能够与 Notion 工作区交互。

设置

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

• 英文版：https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h
• 日文版：https://qiita.com/suekou/items/44c864583f5e3e6325d9

1. 创建 Notion 集成:

   • 访问 Notion Your Integrations 页面。
   • 点击 "New Integration"（新建集成）。
   • 命名您的集成并选择适当的权限（例如，“Read content”（读取内容），“Update content”（更新内容））。

2. 检索密钥:

   • 从您的集成中复制 "Internal Integration Token"（内部集成令牌）。
   • 此令牌将用于身份验证。

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

   • 在 Notion 中打开您希望集成访问的页面或数据库。
   • 点击右上角的 "···" 按钮。
   • 点击 "Connections"（连接）按钮，然后选择您在上面步骤 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"
      }
    }
  }
}

环境变量

• NOTION_API_TOKEN (必需): 您的 Notion API 集成令牌。
• NOTION_MARKDOWN_CONVERSION: 设置为 "true" 以启用实验性的 Markdown 转换。 这可以显著减少查看内容时的令牌消耗，但在尝试编辑页面内容时可能会导致问题。

命令行参数

• --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" 时），使其更具可读性并显著减少令牌消耗。 但是，由于此功能是实验性的，因此在尝试编辑页面内容时可能会导致问题，因为原始结构在转换中会丢失。

您可以通过在工具调用中将 format 参数设置为 "json" 或 "markdown" 来控制每个请求的格式：

• 当仅查看内容时，使用 "markdown" 以获得更好的可读性
• 当您需要修改返回的内容时，使用 "json"

故障排除

如果您遇到权限错误：

1. 确保集成具有所需的权限。
2. 验证集成是否已邀请到相关的页面或数据库。
3. 确认令牌和配置已在 claude_desktop_config.json 中正确设置。

工具

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

• format (string, "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 (number, 默认: 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 (object): 要更新的属性。
   • 返回：有关更新页面的信息。

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 (number, 默认: 100, 最大: 100): 要检索的结果数。
   • 返回：查询的结果列表。

9. notion_retrieve_database

   • 检索有关特定数据库的信息。
   • 必需输入：
     • database_id (string): 要检索的数据库的 ID。
   • 返回：有关该数据库的详细信息。

10. notion_update_database

    • 更新有关数据库的信息。
    • 必需输入：
      • database_id (string): 要更新的数据库的 ID。
    • 可选输入：
      • title (array): 数据库的新标题。
      • description (array): 数据库的新描述。
      • properties (object): 更新的属性模式。
    • 返回：有关更新的数据库的信息。

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 (number, 默认: 100, 最大: 100): 要检索的结果数。
    • 返回：匹配的页面或数据库列表。

13. notion_list_all_users

    • 列出 Notion 工作区中的所有用户。
    • 注意：此功能需要升级到 Notion Enterprise 计划并使用组织 API 密钥，以避免权限错误。
    • 可选输入：
      • start_cursor (string): 用于列出用户的分页起始光标。
      • page_size (number, 最大: 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 中创建评论。
    • 要求集成具有“插入评论”功能。
    • 指定具有 page_id 的 parent 对象或 discussion_id，但不能同时指定两者。
    • 必需输入：
      • rich_text (array): 表示评论内容的富文本对象数组。
    • 可选输入：
      • parent (object): 如果使用，则必须包含 page_id。
      • discussion_id (string): 现有讨论线程 ID。
    • 返回：有关创建的评论的信息。

17. notion_retrieve_comments

    • 从 Notion 页面或块中检索未解决的评论列表。
    • 要求集成具有“读取评论”功能。
    • 必需输入：
      • block_id (string): 要检索其评论的块或页面的 ID。
    • 可选输入：
      • start_cursor (string): 分页起始光标。
      • page_size (number, 最大: 100): 要检索的评论数。
    • 返回：与指定块或页面关联的评论的分页列表。

许可证

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