Zoho CRM MCP サーバー（FastAPI + FastMCP）

FastAPI + FastMCP で構築された本番グレードの Model Context Protocol (MCP) サーバー。Claude やその他の AI クライアントに、Zoho CRM REST API v8 への完全かつ認証済みのアクセスを提供します。レコードの読み取りからモジュール設計、ワークフロー自動化の作成まで対応します。

レコード、COQL、スキーマ設計、ワークフロールールとそのアクション、Webhook、一括/大量操作、タグ、メモ、メール、セキュリティ設定、一括インポート/エクスポートをカバーする 167 の MCP ツール に加え、専用ツールが存在しない Zoho のあらゆる機能にアクセスできる汎用の zoho_api_request エスケープハッチも備えています。

🌟 主な機能

• FastAPI Web フレームワーク: Uvicorn を搭載した高性能・本番対応の ASGI アプリ。

• デュアルトランスポート: Streamable HTTP MCP サーバー（リモート/クラウドホスティング用）と STDIO MCP サーバー（ローカルの Claude Desktop 用）の両方で動作。

• 完全な OAuth 2.0 ライフサイクル: 自動コード交換、ブラウザリダイレクトハンドラー（/auth/callback）、暗号化トークンストレージ、サーバー実行中にトークンを最新に保つバックグラウンドループ。

• チャットで設定可能な認証情報: .env の代わりに、チャットから Zoho Client ID/Secret を提供可能（set_zoho_credentials、または get_auth_url/exchange_auth_code にインラインで渡す）。サーバーを再起動せずに Zoho アカウントを切り替えるのに便利。

• 完全な自動化作成: ワークフロールールをエンドツーエンドで構築 — フィールド更新、メール通知、タスク、Webhook アクションを作成し、トリガーと条件を備えたルールに組み込む。

• スキーマ設計: カスタムモジュール（Zoho が必須とするプロファイル付き）、フィールド、グローバルピックリスト、レイアウト、営業パイプラインを作成。

• スコープ付きセッションモード: 特定のレコード ID に操作を制限する ID ベースの安全フィルター（activate_scope）。

• 人間参加型（HITL）承認: 破壊的操作は実行せずに保留リクエストをキューに入れる。ZOHO_REQUIRE_APPROVAL で切り替え可能。

• 構造化アクティビティログ: すべての認証イベント、API 呼び出し、承認判断が JSON として記録され、get_logs() / GET /logs で取得可能。

• 暗号化トークンストレージ: OAuth トークンは保存時に暗号化（Fernet/AES）。平文では保存されません。

• 堅牢なネットワーククライアント: プール型 httpx クライアント。自動 401 リフレッシュ＆リトライ、429 バックオフのクランプ、指数関数的 5xx リトライ、送信レートリミッター、Zoho のレコード単位レスポンスにおける部分失敗検出を搭載。

• 自動テストスイート: HTTP サーフェス、ツール登録、リクエストペイロード形状、クライアントガードをカバーする 35 の pytest テスト。

Related MCP server: Zoho CRM MCP Server

📁 リポジトリ構造

zoho-crm-mcp/
├── server.py              # FastAPI app + all FastMCP tool definitions & REST endpoints
├── auth_manager.py        # OAuth 2.0 flow, scopes & token refresh
├── zoho_client.py         # Async HTTP client for Zoho CRM API v8 (151 methods)
├── models.py              # Pydantic state & validation models
├── token_store.py         # Encrypted (Fernet) token persistence
├── approval_manager.py    # HITL approval queue for high-risk actions
├── activity_log.py        # Structured JSON activity logger
├── test_server.py         # pytest suite
├── requirements.txt       # Dependencies
├── .env.example           # Environment configuration template
├── pyproject.toml         # Package metadata
└── README.md

⚙️ セットアップとインストール

1. 前提条件

• Python 3.10+

• Zoho CRM API コンソールアプリ（Zoho API Console）

  • クライアントタイプ: Server-based Applications

  • リダイレクト URI: http://localhost:8000/auth/callback（またはデプロイ先のコールバック URL）

2. 環境設定

cp .env.example .env

最小構成:

ZOHO_CLIENT_ID=1000.xxxxxxx
ZOHO_CLIENT_SECRET=xxxxxxx
ZOHO_REDIRECT_URI=http://localhost:8000/auth/callback
ZOHO_DATA_CENTER=com
PORT=8000

サポートされているすべての変数（承認ゲート、OAuth スコープ上書き、レート制限、タイムアウト設定を含む）については .env.example を参照してください。

複数の Zoho アカウントで作業していますか？ ZOHO_CLIENT_ID/ZOHO_CLIENT_SECRET はオプションです。空白のままにして、Claude に set_zoho_credentials(client_id, client_secret, redirect_uri?, data_center?) を呼び出してもらうか、client_id/client_secret を get_auth_url / exchange_auth_code に直接渡してください。client_id を切り替えると、以前のアカウント用に保存されたトークンがクリアされ、別のアプリに発行されたリフレッシュトークンの再利用による Zoho の invalid_client エラーを回避できます。

3. 依存関係のインストール

pip install -r requirements.txt

🚀 実行とデプロイ

オプション A: ローカル FastAPI Web サーバー

python server.py

または Uvicorn を直接使用:

uvicorn server:app --host 0.0.0.0 --port 8000

起動後:

• Web ダッシュボード: http://localhost:8000/

• Swagger ドキュメント: http://localhost:8000/docs

• ヘルスチェック: http://localhost:8000/health

• MCP エンドポイント: http://localhost:8000/mcp

オプション B: ローカル STDIO

python server.py --stdio

オプション C: クラウドデプロイ（Render、Railway、Docker、AWS、Heroku）

• 開始コマンド: uvicorn server:app --host 0.0.0.0 --port $PORT

• ヘルスチェックパス: /health

• 環境変数: ZOHO_CLIENT_ID、ZOHO_CLIENT_SECRET、ZOHO_REDIRECT_URI、ZOHO_DATA_CENTER、ZOHO_TOKEN_ENCRYPTION_KEY を設定（一時ファイルシステム上でもトークンが再起動後も保持されるようにするため）。

🖥️ Claude Desktop 連携

モード 1: HTTP / リモート MCP 接続

{
  "mcpServers": {
    "zoho-crm": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

モード 2: ローカル STDIO 接続

{
  "mcpServers": {
    "zoho-crm": {
      "command": "python",
      "args": ["C:/Users/Lenovo/Desktop/zoho MCP/server.py", "--stdio"],
      "env": {
        "ZOHO_CLIENT_ID": "1000.YOUR_CLIENT_ID",
        "ZOHO_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "ZOHO_REDIRECT_URI": "http://localhost:8000/auth/callback",
        "ZOHO_DATA_CENTER": "com"
      }
    }
  }
}

🔑 初回実行時の OAuth フロー

1. サーバーを起動: python server.py

2. http://localhost:8000/auth/url を開くか、Claude に get_auth_url() を実行してもらう。

3. 返された URL を開き、Zoho CRM にサインインして Accept をクリック。

4. Zoho が /auth/callback?code=... にリダイレクト。サーバーがコードを交換し、暗号化されたトークンを ~/.zoho_crm_tokens.json に保存。

🧩 自動化の構築: ワークフローレシピ

Zoho はワークフロールールを トリガー と 条件 としてモデル化し、各条件は事前に作成された アクション オブジェクトを参照します。この順序で構築してください:

1. get_workflow_configurations(module="Leads")
   -> see which triggers, comparators, and action types this org supports

2. create_field_update_action(
       name="Mark as Hot", module="Leads",
       field_api_name="Rating", value="Hot")
   -> returns the action id

3. create_workflow(
       name="Hot Lead Router",
       module="Leads",
       execute_when={"type": "create_or_edit"},
       conditions=[{
           "sequence_number": 1,
           "criteria_details": {"criteria": {"group_operator": "and", "group": [
               {"comparator": "equal",
                "field": {"api_name": "Lead_Source"},
                "value": "Web Form"}]}},
           "instant_actions": {"actions": [
               {"id": "<action id from step 2>", "type": "field_updates"}]}}])

4. activate_workflow(workflow_id="...")

同じパターンが create_email_notification_action、create_automation_task、create_webhook をアクションソースとして使用する場合にも適用されます。

🎯 スコープ付きセッションモード（安全フィルター）

すべての操作を特定のレコード ID に制限:

• 有効化: activate_scope(module="Deals", record_ids=["4153...001", "4153...002"])

• REST: POST /scope/activate に {"module": "Leads", "record_ids": ["123", "456"]} を送信

• 無効化: deactivate_scope() または POST /scope/deactivate

有効中は、そのモジュールの読み取りはこれらの ID にフィルタリングされ、他の ID への書き込みは OUT_OF_SCOPE で拒否されます。

✅ 人間参加型（HITL）承認

デフォルトでは、破壊的操作は実行せずに保留リクエストをキューに入れ、request_id を返します:

delete_record、bulk_update_records、bulk_delete_records、mass_update_records、mass_delete_records、change_owner、mass_change_owner、merge_records、delete_workflow、delete_workflows、execute_blueprint、update_layout、activate_layout、delete_layout、delete_field、delete_user、delete_tag、bulk_write_create_job。

• 確認: list_pending_approvals() または GET /approvals

• 承認して実行: approve_action(request_id="...") または POST /approvals/{id}/approve

• 拒否して破棄: reject_action(request_id="...") または POST /approvals/{id}/reject

• ゲートを完全に無効化: ZOHO_REQUIRE_APPROVAL=false を設定すると、これらのツールは即座に実行されます。

すべてのリクエスト、承認、拒否はアクティビティログに記録されます。

📜 アクティビティログ

認証イベント、送信 Zoho API 呼び出し、関数実行、承認判断が {timestamp, action, status, details} エントリとして記録され、メモリ内に保持されるとともに ~/.zoho_crm_mcp_activity.log.jsonl に追記されます。

• 取得: get_logs(limit=50, action=None, status=None) または GET /logs

🔐 トークンセキュリティ

• トークンは ~/.zoho_crm_tokens.json に保存時に暗号化（Fernet/AES）されます。

• キーは初回実行時に ~/.zoho_crm_mcp.key へ自動生成されます（POSIX ではユーザーのみ権限）。または ZOHO_TOKEN_ENCRYPTION_KEY で明示的に設定し、コンテナ再起動をまたいで安定したキーを使用できます。

• トークンには発行元の client_id がタグ付けされ、不一致時には破棄されます。これにより、アカウント切り替え後の Zoho の invalid_client エラーを防ぎます。

• 送信呼び出しは 429/5xx バックオフに加えて自己スロットリング（ZOHO_RATE_LIMIT_PER_SEC、デフォルト 10/秒）が適用されます。

🧪 テスト

pytest -v

HTTP サーフェス（/health、/、/auth/*、/scope/*、/approvals/*、/logs）、全 167 の MCP ツールの登録、ワークフロー/モジュール/メモ/通話/Webhook/マージ/ロックで送信される正確なリクエストペイロード、クライアント側バリデーションガード、レート制限のクランプ、Zoho の部分失敗検出をカバーしています。

テストは完全にオフラインで実行されます — Zoho の認証情報は不要です。

🛠️ MCP ツールリファレンス

† デフォルトでは承認が必要です。即時実行するには ZOHO_REQUIRE_APPROVAL=false を設定してください。

* Zoho CRMの公開REST APIにはこの操作のエンドポイントがありません — ブループリントの作成、Deluge関数のソース、レポート/ダッシュボードの作成はUIのみ、または別製品のZoho Analyticsに属します。これらのツールは、存在しないURLに対して失敗するのではなく、動作する代替手段を明示した NOT_SUPPORTED_BY_ZOHO_API メッセージを返します。

🧭 リストにないものへのアクセス

ZohoのAPIは手書きのラッパーよりもはるかに広大です。zoho_api_request が同じ認証、スロットリング、リトライ処理で残りをカバーします：

zoho_api_request(
    method="GET",
    endpoint="settings/territories")

zoho_api_request(
    method="POST",
    endpoint="settings/automation/scoring_rules",
    body={"scoring_rules": [{...}]})

zoho_api_request(
    method="GET",
    endpoint="read/1234567890",
    api_root="bulk")

api_root はURLベースを選択します：crm → {domain}/crm/v8（デフォルト）、bulk → {domain}/crm/bulk/v8、root → {domain}。