Notion MCP 服务器

这是一个为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中打开你希望集成访问的页面或数据库
   • 点击右上角的"···"按钮
   • 点击"连接"按钮，选择你在第一步中创建的集成

4. 配置Claude桌面版：
   在你的claude_desktop_config.json中添加以下内容：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "你的集成令牌"
      }
    }
  }
}

或者

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["你的构建文件路径"],
      "env": {
        "NOTION_API_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": "你的集成令牌",
        "NOTION_MARKDOWN_CONVERSION": "true"
      }
    }
  }
}

或者

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["你的构建文件路径"],
      "env": {
        "NOTION_API_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        # MCP工具模式定义
│   ├── 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"以编程方式访问原始数据结构。注意：只有当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（字符串）：父块的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（字符串）：列出用户的 pagination 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的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文件。