Notion MCP 服务器

一个用于与 Notion API 交互的模型上下文协议 (MCP) 服务器。

概述

本项目实现了一个与 Notion API 交互的 MCP 服务器，允许 AI 模型与 Notion 文档和数据进行交互。它遵循 模型上下文协议 规范，并使用官方的 MCP Python SDK。

要求

• Python 3.12 或更高版本
• uv 用于包管理

安装

# 克隆仓库
git clone https://github.com/flyer103/notion-mcp.git
cd notion-mcp

# 使用 uv 安装依赖
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

配置

在使用 Notion MCP 服务器之前，您需要设置一个 Notion 集成并获取 API 密钥：

1. 前往 https://www.notion.so/my-integrations
2. 创建一个新的集成
3. 将 API 密钥设置为环境变量：

export NOTION_API_KEY="your_api_key_here"

4. 与集成共享您的 Notion 内容：
   • 打开您想要访问的 Notion 页面
   • 点击右上角的 "..." 菜单
   • 选择 "添加连接"
   • 从列表中找到并选择您的集成
   • 该集成现在可以访问此页面及其所有子页面

用法

Notion MCP 服务器支持两种传输方式：

1. 标准输入/输出 (stdio)

这是默认模式，由 Claude for Desktop 和其他 MCP 兼容的 LLM 客户端使用：

python -m notion_mcp.server

2. 服务器发送事件 (SSE)

对于基于 Web 的集成，您可以使用 SSE 传输：

python -m notion_mcp.server --transport sse --host 0.0.0.0 --port 8000

服务器将在 http://localhost:8000/sse 上可用

可用工具

Notion MCP 服务器提供以下功能作为工具：

页面操作

• get_page: 通过 ID 获取 Notion 页面
• update_page: 更新 Notion 页面的属性
• create_page: 创建一个新的 Notion 页面

数据库操作

• get_database: 通过 ID 获取 Notion 数据库
• query_database: 查询 Notion 数据库
• create_database: 创建一个新的 Notion 数据库
• update_database: 更新 Notion 数据库

区块操作

• get_block: 通过 ID 获取 Notion 区块
• update_block: 更新 Notion 区块的内容
• list_blocks: 列出一个区块的子区块
• append_blocks: 将区块附加到一个区块的子区块
• delete_block: 删除一个 Notion 区块

评论操作

• create_comment: 创建一个新的 Notion 评论
• get_comment: 通过 ID 获取 Notion 评论

搜索操作

• search: 搜索 Notion 对象

命令行选项

usage: python -m notion_mcp.server [-h] [--port PORT] [--host HOST] [--transport {stdio,sse}] [--debug]

Notion MCP 服务器

options:
  -h, --help            显示此帮助信息并退出
  --port PORT           SSE 传输监听的端口
  --host HOST           服务器绑定的主机
  --transport {stdio,sse}
                        传输类型 (stdio 或 sse)
  --debug               启用调试模式

使用 Claude for Desktop 进行测试

要将此 MCP 服务器与 Claude for Desktop 一起使用，您需要创建一个配置文件：

1. 在以下位置创建一个名为 claude_desktop_config.json 的文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. 将以下配置添加到文件中（根据需要调整路径）：

{
  "mcpServers": {
    "notion-mcp": {
      "command": "/ABSOLUTE/PATH/TO/YOUR/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/YOUR/notion-mcp",
        "run",
        "-m",
        "notion_mcp.server"
      ],
      "env": {
        "NOTION_API_KEY": "your_notion_api_key"
      }
    }
  }
}

3. 将 /ABSOLUTE/PATH/TO/YOUR/uv 替换为您的 uv 可执行文件的绝对路径
4. 将 /ABSOLUTE/PATH/TO/YOUR/notion-mcp 替换为您的 notion-mcp 安装的绝对路径
5. 将 your_notion_api_key 替换为您的 Notion API 密钥（或者，如果您已将其设置为系统环境变量，则可以省略 env 部分）
6. 保存文件并重新启动 Claude for Desktop

您可以检查 Claude 的日志以查找任何与 MCP 相关的问题：

# 检查 Claude 的日志以查找错误
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Claude 现在可以访问您的 Notion MCP 服务器，并且可以与 Notion 文档进行交互。您可以要求 Claude 执行诸如“在 Notion 中创建一个页面”或“搜索我的 Notion 工作区”之类的操作。

验证配置

要验证 Claude 是否已正确配置为使用您的 Notion MCP 服务器，您可以询问 Claude： “您可以列出您有权访问的工具吗？”或“您可以在我的 Notion 工作区中创建一个新页面吗？”

如果存在任何连接问题，请检查：

• 配置文件格式是否正确且位于正确的位置
• 配置文件中的路径是否正确
• 您的 Notion 集成是否具有正确的权限

解决常见问题

"spawn uv ENOENT" 错误

如果您遇到此错误：

spawn uv ENOENT {"context":"connection","stack":"Error: spawn uv ENOENT\n at ChildProcess._handle.onexit (node:internal/child_process:285:19)\n at onErrorNT (node:internal/child_process:483:16)\n at process.processTicksAndRejections (node:internal/process/task_queues:82:21)"}

这意味着 Claude Desktop 无法在您的 PATH 中找到 uv 可执行文件。要解决此问题：

1. 找到您的 uv 可执行文件的绝对路径：

   # 在 macOS/Linux 上
   which uv
   
   # 在 Windows 上
   where uv
   

2. 在您的配置中使用完整的绝对路径：

   {
     "mcpServers": {
       "notion-mcp": {
         "command": "/ABSOLUTE/PATH/TO/YOUR/uv",
         "args": [
           "--directory",
           "/ABSOLUTE/PATH/TO/YOUR/notion-mcp",
           "run",
           "-m",
           "notion_mcp.server"
         ],
         "env": {
           "NOTION_API_KEY": "your_notion_api_key"
         }
       }
     }
   }
   

3. 保存文件并重新启动 Claude Desktop。

许可证

本项目基于 Apache License 2.0 许可证 - 有关详细信息，请参阅 LICENSE 文件。