MCP Notion Server

🚀 Notion MCP Server

Notion MCP Server 是一个用于 Notion API 的服务器，它能让大语言模型（LLM）与 Notion 工作空间进行交互。此外，该服务器采用 Markdown 转换技术，在与大语言模型通信时减少上下文大小，优化令牌使用，使交互更加高效。

🚀 快速开始

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

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

✨ 主要特性

该项目有以下特性：

• 支持大语言模型与 Notion 工作空间交互。
• 采用 Markdown 转换技术，优化令牌使用。

📦 安装指南

具体步骤

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", "@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_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

💻 使用示例

基础用法

{
  "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_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              # 入口点和命令行处理
│   ├── 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 中创建评论。
    • 要求集成具有 'insert comment' 功能。
    • 要么指定包含 page_id 的 parent 对象，要么指定 discussion_id，但不能同时指定两者。
    • 必需输入：
      • rich_text（数组）：表示评论内容的富文本对象数组。
    • 可选输入：
      • parent（对象）：如果使用，必须包含 page_id。
      • discussion_id（字符串）：现有的讨论线程 ID。
    • 返回：关于创建的评论的信息。

17. notion_retrieve_comments

    • 从 Notion 页面或块中检索未解决的评论列表。
    • 要求集成具有 'read comment' 功能。
    • 必需输入：
      • block_id（字符串）：要检索其评论的块或页面的 ID。
    • 可选输入：
      • start_cursor（字符串）：分页起始游标。
      • page_size（数字，最大：100）：要检索的评论数。
    • 返回：与指定块或页面关联的评论的分页列表。

📄 许可证

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