Notion MCP Client

Notion MCP 客户端

一个用于与 Notion API 交互的模型上下文协议（MCP）客户端。此客户端旨在用于支持 MCP 扩展功能的现代 AI 工具，例如 Claude。

功能

• 支持重试逻辑的异步 API 操作
• 并发控制，以遵守 Notion API 速率限制
• 基于环境变量的配置
• 基于 JSON 的操作配置
• 支持 MCP 的灵活服务实现
• MCP 不可用时回退到标准 HTTP API

安装

pip install notion-mcp

或从源代码安装：

git clone https://github.com/yourusername/notion-mcp.git
cd notion-mcp
pip install -e .

如需支持 MCP，请使用 MCP extra 安装：

pip install notion-mcp[mcp]

配置

创建 .env 文件，填写 Notion API 凭据和配置：

NOTION_TOKEN=your_notion_token_here
ROOT_PAGE_ID=your_root_page_id_here
MAX_RETRIES=3
RETRY_DELAYS=1,3,5
CONCURRENCY_LIMIT=5
TIMEOUT_MS=30000

用法

命令行

使用默认配置运行：

notion-mcp

使用自定义 JSON 配置文件运行：

notion-mcp config.json

服务

启动服务（如果支持，则启用 MCP）：

notion-mcp-server --host 0.0.0.0 --port 8000

如果可用，服务将尝试使用 MCP 协议。如果不可用，则会回退到标准 HTTP 服务，该服务接受发送到 /notion 的 POST 请求。

HTTP API

使用 HTTP API 时，向 /notion 发送包含 JSON 请求体的 POST 请求：

{
  "root_page_id": "your_page_id_here",
  "database_filter": ["Articles", "Resources"],
  "operation": {
    "type": "fill_web_url",
    "params": {
      "web_field": "网址"
    }
  }
}

使用 curl 的示例：

curl -X POST http://localhost:8000/notion \
  -H "Content-Type: application/json" \
  -d '{"root_page_id": "your_page_id_here", "operation": {"type": "fill_web_url"}}'

JSON 配置

创建 JSON 配置文件以自定义行为：

{
  "root_page_id": "your_page_id_here",
  "database_filter": ["Articles", "Resources"],
  "operation": {
    "type": "fill_web_url",
    "params": {
      "web_field": "网址"
    }
  }
}

与 Claude 配合使用

要将此 MCP 客户端与 Claude 配合使用，需要先设置服务，然后配置 Claude 以使用它。以下是一个配置示例：

{
  "mcp_configurations": [
    {
      "name": "notion",
      "endpoint": "http://localhost:8000/notion",
      "description": "Access and manipulate Notion databases and pages"
    }
  ]
}

然后，在与 Claude 的对话中，可以像这样请求它执行 Notion 操作：

Claude, please use the notion MCP to fill the web URL field in all pages of my Articles database.

与其他框架集成

NotionRequestHandler 类提供了一种灵活的方式，可与不同的框架集成：

from notion_mcp.handler import notion_handler

# Create an adapter for your framework
async def my_framework_handler(request):
    # Extract data from your framework's request object
    input_data = await request.json()
    
    # Process with Notion handler
    result = await notion_handler.handle_request(input_data)
    
    # Return in your framework's response format
    return MyFrameworkResponse(json=result)

可用操作

• fill_web_url：查找页面中的 URL 字段，并将值复制到指定的目标 URL 字段
• 更多操作即将推出！

开发

如需为此项目做出贡献：

1. Fork 此代码库
2. 创建虚拟环境：python -m venv venv
3. 激活环境：source venv/bin/activate（Linux/Mac）或 venv\Scripts\activate（Windows）
4. 安装开发依赖项：pip install -e ".[dev]"
5. 进行更改
6. 运行测试：pytest
7. 提交 pull request

许可证

MIT