Notion MCP 服务器

一个暴露官方 Notion SDK 的模型上下文协议 (MCP) 服务器，允许 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: 设置 > 高级 > 模型上下文协议
• Cursor AI: 设置 > AI > MCP 服务器
• Claude.ai (网页版): 个人资料 > 设置 > API 与集成 > 模型上下文协议

可用工具

服务器提供与 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"
      ]
    }
  }
}

命令行选项

选项：
  -h, --help              显示帮助信息
  -v, --version           显示版本信息
  --verbose               启用详细日志
  --env-path <路径>       .env 文件路径
  --api-key <密钥>        Notion API 密钥
  -y                      跳过确认提示

故障排除

如遇"Failed to create client"错误：

• Windows 系统可尝试在 npx 命令前添加 cmd /c
• macOS/Linux 系统可尝试使用 npx 的完整路径
• 添加到 AI 助手前先在终端测试命令

常见问题

• "No access to resource"错误: 确认已按照步骤 2 将特定 Notion 页面或数据库共享给集成
• 共享菜单中不显示集成: 尝试刷新页面或重启浏览器
• 功能受限: 检查 Notion 集成设置中是否启用了适当的功能

功能特点

• 通过官方 SDK 全面支持 Notion API
• 符合 MCP 标准，实现无缝 AI 集成
• 提供完整的 Notion 操作工具集
• 具有详细消息的健壮错误处理
• 支持环境变量的简易配置

各工具的详细文档参见 工具文档。

许可证

本项目采用 Apache License 2.0 许可 - 详见 LICENSE 文件。