Notion MCP Client

Notion MCP クライアント

Notion API と連携するための Model Context Protocol（MCP）クライアントです。このクライアントは、MCP による機能拡張をサポートする Claude などの最新の AI ツールで使用することを想定しています。

特長

• リトライロジックを備えた非同期 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 エクストラを指定してインストールします。

pip install notion-mcp[mcp]

設定

Notion API の認証情報と設定を含む .env ファイルを作成します。

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 プロトコルを使用しようとします。利用できない場合は、/notion への POST リクエストを受け付ける標準 HTTP サーバーにフォールバックします。

HTTP API

HTTP API を使用する場合は、JSON ボディを指定して /notion に 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. リポジトリをフォークします
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. プルリクエストを送信します

ライセンス

MIT