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）集成。希望對您有所幫助！