Notion MCP Server

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 集成页面。
   • 点击“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（字符串，可选值为 "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（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 计划并使用 Organization API 密钥，以避免权限错误。
    • 可选输入：
      • start_cursor（string）：列出用户时使用的分页起始游标。
      • page_size（number，最大值：100）：要获取的用户数量。
    • 返回：工作区中所有用户的分页列表。

14. notion_retrieve_user

    • 在 Notion 中通过 user_id 检索指定用户。
    • 注意：此功能需要升级到 Notion Enterprise 计划，并使用 Organization API 密钥，以避免权限错误。
    • 必填输入：
      • user_id (string)：要检索的用户 ID。
    • 返回：指定用户的详细信息。

15. notion_retrieve_bot_user

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

16. notion_create_comment

    • 在 Notion 中创建评论。
    • 需要集成具备“插入评论”权限。
    • 指定包含 page_id 的 parent 对象或 discussion_id，但不能同时指定两者。
    • 必填输入：
      • 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 文件。