AI导哈

Notion MCP服务器

一个用于与Notion API交互的模型上下文协议（MCP）服务器，允许AI模型与Notion文档和数据交互。

  • by flyer103
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 flyer103/notion-mcp

使用说明

MCP服务器概念

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

概述

该项目实现了一个MCP服务器，该服务器与Notion的API接口，允许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"
  1. 通过集成共享您的Notion内容：
    • 打开要访问的Notion页面
    • 点击右上角的“…”菜单
    • 选择“添加连接”
    • 从列表中查找并选择您的集成
    • 集成现在可以访问此页面及其所有子页面

用法

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

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

这是默认模式，Claude用于桌面和其他兼容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获取通知页面
  • 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进行桌面测试

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

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

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • 视窗: %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"
      }
    }
  }
}
  1. 替换 /ABSOLUTE/PATH/TO/YOUR/uv 与你的绝对路径 uv 可执行
  2. 替换 /ABSOLUTE/PATH/TO/YOUR/notion-mcp 了解mcp安装的绝对路径
  3. 替换 your_notion_api_key 使用Notion API键（或者，如果将env部分设置为系统环境变量，则可以省略该部分）
  4. 保存文件并重新启动Claude for Desktop

您可以查看克劳德的日志，了解任何与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无法找到 uv 可在PATH中执行。要解决此问题，请执行以下操作：

  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文件。

相关 MCP