Notion MCP Server

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

配置

以下是上述步骤的详细解释，请参阅以下文章：

• 英文版：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转换。这可以显著减少查看内容时的令牌消耗，但可能会导致编辑页面内容时出现问题。

命令行参数

• --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中的令牌和配置正确设置。

项目结构

该项目以模块化方式组织，以提高可维护性和可读性：

./
├── src/
│   ├── index.ts              # 入口点和命令行处理
│   ├── client/
│   │   └── index.ts          # NotionClientWrapper类用于API交互
│   ├── 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

    • 根据user_id在Notion中检索特定用户。
    • 注意：此功能需要升级到Notion企业计划并使用组织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文件。 </中文翻译>