Notion 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 集成：

   • 访问 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"
      }
    }
  }
}

环境变量

• 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 转换以减少 token 消耗：

{
  "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”时，响应将在 format 参数设置为“markdown”时转换为 Markdown 格式，使其更易于阅读，并显著减少 token 消耗。然而，由于此功能仍处于实验阶段，它可能会在尝试编辑页面内容时引发问题，因为原始结构会在转换过程中丢失。

您可以通过在工具调用中将 format 参数设置为“json”或“markdown”，来按请求控制格式：

• 仅查看内容时使用“markdown”以获得更好的可读性。
• 需要修改返回内容时使用“json”。

故障排除

如果您遇到权限错误：

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

项目结构

该项目采用模块化设计，以提高可维护性和可读性：

./
├── src/
│   ├── index.ts              # 入口点及命令行处理
│   ├── client/
│   │   └── index.ts          # 用于 API 交互的 NotionClientWrapper 类
│   ├── server/
│   │   └── index.ts          # MCP 服务器的设置及请求处理
│   ├── types/
│   │   ├── index.ts          # 类型导出
│   │   ├── args.ts           # 工具参数接口
│   │   ├── common.ts         # 公共模式定义
│   │   ├── responses.ts      # API 响应类型定义
│   │   └── schemas.ts        # 工具模式定义
│   ├── utils/
│   │   └── index.ts          # 工具函数
│   └── markdown/
│       └── index.ts          # Markdown 转换工具

目录说明

• 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”以便程序化访问原始数据结构。注意：Markdown 转换仅在 NOTION_MARKDOWN_CONVERSION 环境变量设置为“true”时有效。

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 企业版，并使用组织 API 密钥，以避免权限错误。
    • 可选输入：
      • start_cursor（字符串）：列出用户的分页起始游标。
      • page_size（数字，最大值：100）：要检索的用户数量。
    • 返回：工作区中所有用户的分页列表。

14. notion_retrieve_user

    • 根据用户 ID 检索 Notion 中的特定用户。
    • 注意：此函数需要升级到 Notion 企业版，并使用组织 API 密钥，以避免权限错误。
    • 必需输入：
      • user_id（字符串）：要检索的用户的 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 文件。

mcp-notion-server 快速上手指南

mcp-notion-server 是一个 MCP（Model Context Protocol）服务器，旨在让大语言模型（如 Claude）能够与 Notion 工作空间进行交互。它支持将 Notion 内容转换为 Markdown 格式，从而显著减少 Token 消耗，提升交互效率。

环境准备

在开始之前，请确保满足以下条件：

• 操作系统：Windows、macOS 或 Linux。
• 运行时依赖：已安装 Node.js (推荐 v18 或更高版本)。
• 前置软件：已安装并配置好 Claude Desktop 客户端。
• Notion 账号：拥有可创建 Integration 的 Notion 工作空间权限。

安装与配置步骤

1. 创建 Notion 集成 (Integration)

1. 访问 Notion Integrations 页面。
2. 点击 "+ New integration"。
3. 填写名称（例如 MCP Server），选择关联的工作空间，权限建议勾选 "Read content" 和 "Update content"。
4. 提交后，复制生成的 Internal Integration Token（以 secret_ 开头），后续配置需用到。

2. 授权集成访问工作空间

1. 打开你希望 AI 访问的 Notion 页面或数据库。
2. 点击右上角的 "···" 菜单。
3. 选择 "Connections"。
4. 在搜索框中找到并选中你在第 1 步创建的集成名称。

3. 配置 Claude Desktop

找到 Claude Desktop 的配置文件 claude_desktop_config.json：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

在文件中添加以下配置（请将 your-integration-token 替换为你复制的 Token）：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

提示：如果你希望启用实验性的 Markdown 转换功能以节省 Token，可在 env 中增加 "NOTION_MARKDOWN_CONVERSION": "true"。

4. 重启 Claude Desktop

保存配置文件后，完全退出并重新启动 Claude Desktop 应用，使配置生效。

基本使用

配置完成后，你可以在与 Claude 的对话中直接通过自然语言操作 Notion。

使用示例：

• 查询内容：

  "帮我查找 Notion 中关于'项目计划'的页面，并总结主要内容。" （系统会自动调用 notion_search 和 notion_retrieve_page 工具）

• 更新数据：

  "在'任务追踪'数据库中添加一条新记录，任务是'修复登录 Bug'，状态设为'进行中'。" （系统会自动调用 notion_create_database_item 工具）

• 指定输出格式（高级用法）： 如果在配置中启用了 NOTION_MARKDOWN_CONVERSION，AI 默认会以更易读的 Markdown 格式返回内容。若需获取原始数据结构进行编程处理，可在对话中要求："请以 JSON 格式返回该页面的详细属性。"

验证工具列表（可选）： 如果你只想启用只读工具以提高安全性，可以在启动命令中加入参数：

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

(注：使用 npx 方式启动时，需在 args 数组中相应调整参数)