Notion MCP Server

Notion MCP 服务

一个模型上下文协议（MCP）服务，通过官方 Notion SDK 开放功能，让 AI 模型能够与 Notion 工作区交互。

快速开始

1. 设置 Notion 集成

1. 前往 https://www.notion.so/my-integrations
2. 创建新的集成
3. 复制 API 密钥

2. 将 Notion 页面连接到集成

若要让集成访问 Notion 内容，你需要明确地将页面或数据库共享给它：

1. 前往你想通过集成访问的 Notion 页面或数据库
2. 点击右上角的“Share”按钮
3. 在“Add people, groups, or integrations”字段中，从下拉列表选择你的集成
4. 点击“Invite”
5. 对每个想要开放访问的页面或数据库重复此操作

注意： 集成只能访问明确共享给它的页面和数据库。子页面会自动继承父页面的访问权限。

3. 添加到 AI 助手

你可以使用以下任一配置格式，将此 MCP 服务添加到 Claude Desktop、Cursor AI 或 Claude.ai：

命令行格式

npx @ramidecodes/mcp-server-notion@latest -y --api-key=your-notion-integration-key

JSON 配置格式

{
  "mcpServers": {
    "Notion": {
      "command": "npx",
      "args": [
        "@ramidecodes/mcp-server-notion@latest",
        "-y",
        "--api-key=your-notion-integration-key"
      ]
    }
  }
}

将 your-notion-integration-key 替换为第 1 步中的 API 密钥。

设置说明

• Claude Desktop：Settings > Advanced > Model Context Protocol
• Cursor AI：Settings > AI > MCP Servers
• Claude.ai (Web)：Profile > Settings > API & Integrations > Model Context Protocol

可用工具

此服务提供用于与 Notion 交互的工具：

• 搜索：查找页面或数据库
• 数据库：查询和检索数据库条目
• 页面：创建、检索和更新页面
• 区块：管理内容区块（段落、列表等）
• 用户：列出用户并获取用户信息
• 评论：创建和列出评论
• 链接预览：为 URL 创建链接预览

其他设置方法

使用环境变量

你可以使用 .env 文件，而不是直接传入 API 密钥：

1. 创建 .env 文件，内容如下：

NOTION_API_KEY=your-notion-integration-key

2. 运行服务：

npx @ramidecodes/mcp-server-notion@latest -y

使用环境变量的 JSON 配置（适用于 Claude Desktop）

你也可以在 JSON 配置格式中使用环境变量：

{
  "mcpServers": {
    "Notion": {
      "command": "npx",
      "args": [
        "@ramidecodes/mcp-server-notion@latest",
        "-y",
        "--api-key=your-notion-integration-key"
      ]
    }
  }
}

命令行选项

OPTIONS:
  -h, --help              Show help message
  -v, --version           Show version information
  --verbose               Enable verbose logging
  --env-path <path>       Path to .env file
  --api-key <key>         Notion API key
  -y                      Skip confirmation prompts

故障排除

如果遇到“Failed to create client”错误：

• 在 Windows 上，尝试在 npx 命令前使用 cmd /c
• 在 macOS/Linux 上，尝试使用 npx 的完整路径
• 将命令添加到 AI 助手之前，先在终端中进行测试

常见问题

• “No access to resource”错误：请确保已将特定 Notion 页面或数据库共享给集成（参见第 2 步）
• 共享菜单中未显示集成：尝试刷新页面或重启浏览器
• 功能受限：检查 Notion 集成设置中是否已为集成启用相应权限

功能

• 通过官方 SDK 完整支持 Notion API
• 符合 MCP 规范，可与 AI 无缝集成
• 提供涵盖所有 Notion 操作的全面工具
• 具备可靠的错误处理，并提供详细信息
• 可通过环境变量轻松配置

如需了解各工具的详细文档，请参阅工具文档。

许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。