Notion MCP Server

Notion MCP 服务

用于与 Notion API 交互的模型上下文协议（MCP）服务。

概述

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

要求

• Python 3.12 或更高版本
• 使用 uv 进行包管理

安装

# Clone the repository
git clone https://github.com/flyer103/notion-mcp.git
cd notion-mcp

# Install dependencies using 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 页面
   • 点击右上角的“...”菜单
   • 选择“Add connections”
   • 在列表中找到并选择你的集成
   • 现在，该集成可以访问此页面及其所有子页面

使用方法

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

1. 标准输入/输出（stdio）

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

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 Server

options:
  -h, --help            show this help message and exit
  --port PORT           Port to listen on for SSE transport
  --host HOST           Host to bind the server to
  --transport {stdio,sse}
                        Transport type (stdio or sse)
  --debug               Enable debug mode

使用 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 相关问题：

# Check Claude's logs for errors
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 可执行文件的绝对路径：

   # On macOS/Linux
   which uv
   
   # On 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 文件。