Notion MCP

🚀 Notion MCP 客户端

Notion MCP 客户端是一个用于与 Notion API 交互的 Model Context Protocol (MCP) 客户端。它专为现代 AI 工具（如 Claude）设计，支持 MCP 扩展功能，能有效提升与 Notion API 交互的效率和灵活性。

✨ 主要特性

• 异步 API 操作带有重试逻辑，确保在网络不稳定等情况下操作的可靠性。
• 并发控制以尊重 Notion API 的速率限制，避免因频繁请求导致的封禁。
• 环境基于配置，方便根据不同的使用场景进行灵活调整。
• JSON 基于操作配置，使配置更加直观和易于管理。
• 具有 MCP 支持的灵活服务器实现，提供更多的交互方式。
• 当 MCP 不可用时回退到标准 HTTP API，保证服务的可用性。

📦 安装指南

通过 pip 安装

pip install notion-mcp

从源码安装

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

带有 MCP 支持的额外安装

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 发送 POST 请求，并带有 JSON 正文：

{
  "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

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

{
  "mcp_configurations": [
    {
      "name": "notion",
      "endpoint": "http://localhost:8000/notion",
      "description": "访问和操作 Notion 数据"
    }
  ]
}

开发

要贡献或扩展此项目，请克隆仓库并查看 CONTRIBUTING.md 文件。

此文档详细介绍了如何安装、配置和使用 Notion MCP 客户端，以及如何与现代 AI 工具（如 Claude）集成。希望对您有所帮助！