🚀 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 转换技术，优化令牌使用。
📦 安装指南
具体步骤
- 创建 Notion 集成：
- 访问 Notion 集成页面。
- 点击“New Integration”。
- 为集成命名并选择适当的权限（例如，“Read content”、“Update content”）。
- 获取密钥：
- 从你的集成中复制“Internal Integration Token”。
- 此令牌将用于身份验证。
- 将集成添加到工作空间：
- 在 Notion 中打开你希望集成访问的页面或数据库。
- 点击右上角的“···”按钮。
- 点击“Connections”按钮，选择你在步骤 1 中创建的集成。
- 配置 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"。
📚 详细文档
故障排除
如果你遇到权限错误：
- 确保集成具有所需的权限。
- 验证集成是否已被邀请到相关页面或数据库。
- 确认令牌和配置是否已在
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" 时有效。
-
notion_append_block_children- 向父块追加子块。
- 必需输入：
block_id（字符串）：父块的 ID。children（数组）：要追加的块对象数组。
- 返回：关于追加块的信息。
-
notion_retrieve_block- 检索特定块的信息。
- 必需输入：
block_id（字符串）：要检索的块的 ID。
- 返回：关于该块的详细信息。
-
notion_retrieve_block_children- 检索特定块的子块。
- 必需输入：
block_id（字符串）：父块的 ID。
- 可选输入：
start_cursor（字符串）：下一页结果的游标。page_size（数字，默认：100，最大：100）：要检索的块数。
- 返回：子块列表。
-
notion_delete_block- 删除特定块。
- 必需输入：
block_id（字符串）：要删除的块的 ID。
- 返回：删除确认信息。
-
notion_retrieve_page- 检索特定页面的信息。
- 必需输入：
page_id（字符串）：要检索的页面的 ID。
- 返回：关于该页面的详细信息。
-
notion_update_page_properties- 更新页面的属性。
- 必需输入：
page_id（字符串）：要更新的页面的 ID。properties（对象）：要更新的属性。
- 返回：关于更新后页面的信息。
-
notion_create_database- 创建新数据库。
- 必需输入：
parent（对象）：数据库的父对象。properties（对象）：数据库的属性模式。
- 可选输入：
title（数组）：数据库的标题，以富文本数组形式表示。
- 返回：关于创建的数据库的信息。
-
notion_query_database- 查询数据库。
- 必需输入：
database_id（字符串）：要查询的数据库的 ID。
- 可选输入：
filter（对象）：过滤条件。sorts（数组）：排序条件。start_cursor（字符串）：下一页结果的游标。page_size（数字，默认：100，最大：100）：要检索的结果数。
- 返回：查询结果列表。
-
notion_retrieve_database- 检索特定数据库的信息。
- 必需输入：
database_id（字符串）：要检索的数据库的 ID。
- 返回：关于该数据库的详细信息。
-
notion_update_database- 更新数据库的信息。
- 必需输入：
database_id（字符串）：要更新的数据库的 ID。
- 可选输入：
title（数组）：数据库的新标题。description（数组）：数据库的新描述。properties（对象）：更新后的属性模式。
- 返回：关于更新后数据库的信息。
-
notion_create_database_item- 在 Notion 数据库中创建新项。
- 必需输入：
database_id（字符串）：要添加项的数据库的 ID。properties（对象）：新项的属性。这些属性应与数据库模式匹配。
- 返回：关于新创建项的信息。
-
notion_search- 按标题搜索页面或数据库。
- 可选输入：
query（字符串）：在页面或数据库标题中搜索的文本。filter（对象）：将结果限制为仅页面或仅数据库的条件。sort（对象）：对结果进行排序的条件。start_cursor（字符串）：分页起始游标。page_size（数字，默认：100，最大：100）：要检索的结果数。
- 返回：匹配的页面或数据库列表。
-
notion_list_all_users- 列出 Notion 工作空间中的所有用户。
- 注意：此功能需要升级到 Notion 企业版计划并使用组织 API 密钥，以避免权限错误。
- 可选输入：
- start_cursor（字符串）：列出用户的分页起始游标。
- page_size（数字，最大：100）：要检索的用户数。
- 返回：工作空间中所有用户的分页列表。
-
notion_retrieve_user- 通过用户 ID 在 Notion 中检索特定用户。
- 注意：此功能需要升级到 Notion 企业版计划并使用组织 API 密钥，以避免权限错误。
- 必需输入：
- user_id（字符串）：要检索的用户的 ID。
- 返回：关于指定用户的详细信息。
-
notion_retrieve_bot_user- 检索与当前令牌关联的 Notion 机器人用户。
- 返回：关于机器人用户的信息，包括授权集成的人员的详细信息。
-
notion_create_comment- 在 Notion 中创建评论。
- 要求集成具有 'insert comment' 功能。
- 要么指定包含
page_id的parent对象，要么指定discussion_id，但不能同时指定两者。 - 必需输入：
rich_text（数组）：表示评论内容的富文本对象数组。
- 可选输入：
parent（对象）：如果使用，必须包含page_id。discussion_id（字符串）：现有的讨论线程 ID。
- 返回：关于创建的评论的信息。
-
notion_retrieve_comments- 从 Notion 页面或块中检索未解决的评论列表。
- 要求集成具有 'read comment' 功能。
- 必需输入：
block_id（字符串）：要检索其评论的块或页面的 ID。
- 可选输入：
start_cursor（字符串）：分页起始游标。page_size（数字，最大：100）：要检索的评论数。
- 返回：与指定块或页面关联的评论的分页列表。
📄 许可证
此 MCP 服务器采用 MIT 许可证。这意味着你可以自由使用、修改和分发该软件，但需遵守 MIT 许可证的条款和条件。有关更多详细信息，请参阅项目仓库中的 LICENSE 文件。