Notion MCP Server

Notion API的MCP服务器，使LLM能够与Notion工作空间交互。此外，它采用Markdown转换功能，在与LLM通信时减少上下文大小，优化token使用，使交互更高效。

Setup

以下详细解释了前面提到的步骤：

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

创建Notion集成：
- 访问Notion您的集成页面。
- 点击"新建集成"。
- 为您的集成命名并选择适当的权限（例如："读取内容"、"更新内容"）。
获取密钥：
- 复制您的集成的"内部集成令牌"。
- 此令牌将用于身份验证。
将集成添加到工作空间：
- 在Notion中打开您希望集成访问的页面或数据库。
- 点击右上角的"···"按钮。
- 点击"连接"按钮，并选择步骤1中创建的集成。
配置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"时，响应将被转换为Markdown格式（当format参数设置为"markdown"时），使其更易于阅读并显著减少token消耗。但由于此功能是实验性的，在转换过程中可能会丢失原始结构，导致编辑页面内容时出现问题。

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

使用"markdown"以获得更好的可读性，当您仅查看内容时
使用"json"，当您需要修改返回的内容时

故障排除

如果您遇到权限错误：

确保集成具有所需的权限。
验证集成是否已邀请到相关页面或数据库。
确认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 (string, "json"或"markdown", 默认："markdown")：控制响应格式。使用"markdown"获取可读输出，"json"获取对原始数据结构的程序化访问。注意：Markdown转换仅在NOTION_MARKDOWN_CONVERSION环境变量设置为"true"时才有效。

notion_append_block_children
- 将子块附加到父块。
- 必需输入：
  - block_id (string)：父块的ID。
  - children (array)：要附加的块对象数组。
- 返回：附加块的信息。
notion_retrieve_block
- 获取特定块的信息。
- 必需输入：
  - block_id (string)：要获取的块的ID。
- 返回：块的详细信息。
notion_retrieve_block_children
- 获取特定块的子块。
- 必需输入：
  - block_id (string)：父块的ID。
- 可选输入：
  - start_cursor (string)：下一页结果的游标。
  - page_size (number, 默认：100, 最大：100)：要检索的块数量。
- 返回：子块列表。
notion_delete_block
- 删除特定块。
- 必需输入：
  - block_id (string)：要删除的块的ID。
- 返回：删除确认。
notion_retrieve_page
- 获取特定页面的信息。
- 必需输入：
  - page_id (string)：要获取的页面的ID。
- 返回：页面的详细信息。
notion_update_page_properties
- 更新页面属性。
- 必需输入：
  - page_id (string)：要更新的页面的ID。
  - properties (object)：要更新的属性。
- 返回：更新页面的信息。
notion_create_database
- 创建新数据库。
- 必需输入：
  - parent (object)：数据库的父对象。
  - properties (object)：数据库的属性模式。
- 可选输入：
  - title (array)：作为富文本数组的数据库标题。
- 返回：创建数据库的信息。
notion_query_database
- 查询数据库。
- 必需输入：
  - database_id (string)：要查询的数据库的ID。
- 可选输入：
  - filter (object)：过滤条件。
  - sorts (array)：排序条件。
  - start_cursor (string)：下一页结果的游标。
  - page_size (number, 默认：100, 最大：100)：要检索的结果数量。
- 返回：查询结果列表。
notion_retrieve_database
- 获取特定数据库的信息。
- 必需输入：
  - database_id (string)：要获取的数据库的ID。
- 返回：数据库的详细信息。
notion_update_database
- 更新数据库信息。
- 必需输入：
  - database_id (string)：要更新的数据库的ID。
- 可选输入：
  - title (array)：数据库的新标题。
  - description (array)：数据库的新描述。
  - properties (object)：更新的属性模式。
- 返回：更新数据库的信息。
notion_create_database_item
- 在Notion数据库中创建新条目。
- 必需输入：
  - database_id (string)：要添加条目的数据库的ID。
  - properties (object)：新条目的属性。这些应与数据库模式匹配。
- 返回：新创建条目的信息。
notion_search
- 通过标题搜索页面或数据库。
- 可选输入：
  - query (string)：要在页面或数据库标题中搜索的文本。
  - filter (object)：限制结果为仅页面或仅数据库的标准。
  - sort (object)：排序结果的标准
  - start_cursor (string)：分页起始游标。
  - page_size (number, 默认：100, 最大：100)：要检索的结果数量。
- 返回：匹配的页面或数据库列表。
notion_list_all_users
- 列出Notion工作空间中的所有用户。
- 注意：此功能需要升级到Notion企业版并使用组织API密钥以避免权限错误。
- 可选输入：
  - start_cursor (string)：列出用户的分页起始游标。
  - page_size (number, 最大：100)：要检索的用户数量。
- 返回：工作空间中所有用户的分页列表。
notion_retrieve_user
- 通过Notion中的user_id检索特定用户。
- 注意：此功能需要升级到Notion企业版并使用组织API密钥以避免权限错误。
- 必需输入：
  - user_id (string)：要检索的用户ID。
- 返回：指定用户的详细信息。
notion_retrieve_bot_user
- 检索与当前令牌关联的Notion机器人用户。
- 返回：机器人用户的信息，包括授权集成的人员详情。
notion_create_comment
- 在Notion中创建评论。
- 需要集成具有"插入评论"功能。
- 必须指定一个带有page_id的parent对象或一个discussion_id，但不能同时指定。
- 必需输入：
  - rich_text (array)：表示评论内容的富文本对象数组。
- 可选输入：
  - parent (object)：如果使用，必须包含page_id。
  - discussion_id (string)：现有的讨论线程ID。
- 返回：创建评论的信息。
notion_retrieve_comments
- 从Notion页面或块中检索未解决的评论列表。
- 需要集成具有"读取评论"功能。
- 必需输入：
  - block_id (string)：要检索其评论的块或页面的ID。
- 可选输入：
  - start_cursor (string)：分页起始游标。
  - page_size (number, 最大：100)：要检索的评论数量。
- 返回：与指定块或页面关联的评论分页列表。

许可证

此MCP服务器根据MIT许可证授权。这意味着您可以自由使用、修改和分发该软件，但需遵守MIT许可证的条款和条件。更多详情请参阅项目存储库中的LICENSE文件。

suekou/mcp-notion-server

星标增长

证据时间轴