Zoho CRM MCP Server (FastAPI + FastMCP)

Ein produktionsreifer Model Context Protocol (MCP)-Server, gebaut mit FastAPI + FastMCP, der Claude und anderen KI-Clients vollständigen, authentifizierten Zugriff auf die Zoho CRM REST API v8 bietet – vom Lesen von Datensätzen über das Entwerfen von Modulen bis hin zum Erstellen von Workflow-Automatisierungen.

167 MCP-Tools für Datensätze, COQL, Schema-Design, Workflow-Regeln und deren Aktionen, Webhooks, Bulk-/Massenoperationen, Tags, Notizen, E-Mail, Sicherheitseinstellungen sowie Bulk-Import/-Export – plus einen generischen zoho_api_request-Notausgang für alles, was Zoho bereitstellt, wofür es kein dediziertes Tool gibt.

🌟 Hauptfunktionen

• FastAPI-Webframework: Hochleistungsfähige, produktionsreife ASGI-App, betrieben mit Uvicorn.

• Dualer Transport: Läuft als Streamable-HTTP-MCP-Server (für Remote-/Cloud-Hosting) und als STDIO-MCP-Server (für lokales Claude Desktop).

• Vollständiger OAuth-2.0-Lebenszyklus: Automatischer Code-Austausch, Browser-Redirect-Handler (/auth/callback), verschlüsselte Token-Speicherung und eine Hintergrundschleife, die das Token aktualisiert, solange der Server läuft.

• Über Chat konfigurierbare Anmeldedaten: Zoho-Client-ID/Secret aus dem Chat bereitstellen (set_zoho_credentials oder inline bei get_auth_url/exchange_auth_code) statt über .env – nützlich zum Wechseln von Zoho-Konten ohne Neustart.

• Vollständige Automatisierungserstellung: Workflow-Regeln von Anfang bis Ende erstellen – Feldaktualisierungs-, E-Mail-Benachrichtigungs-, Aufgaben- und Webhook-Aktionen anlegen und sie dann mit Triggern und Kriterien in eine Regel einbinden.

• Schema-Design: Benutzerdefinierte Module (mit den von Zoho vorgeschriebenen Profilen), Felder, globale Picklists, Layouts und Vertriebspipelines erstellen.

• Scoped-Session-Modus: ID-basierter Sicherheitsfilter (activate_scope), der Operationen auf bestimmte Datensatz-IDs beschränkt.

• Human-In-The-Loop-Genehmigungen: Destruktive Aktionen stellen eine ausstehende Anfrage in die Warteschlange, statt sie auszuführen. Umschaltbar mit ZOHO_REQUIRE_APPROVAL.

• Strukturierte Aktivitätsprotokollierung: Jedes Auth-Ereignis, jeder API-Aufruf und jede Genehmigungsentscheidung wird als JSON protokolliert und ist über get_logs() / GET /logs abrufbar.

• Verschlüsselte Token-Speicherung: OAuth-Tokens werden im Ruhezustand verschlüsselt (Fernet/AES), niemals im Klartext.

• Robuster Netzwerk-Client: Gepoolter httpx-Client mit automatischem 401-Refresh-und-Retry, begrenztem 429-Backoff, exponentiellem 5xx-Retry, einem ausgehenden Ratenbegrenzer und Erkennung von Teilfehlern bei Zohos Antworten pro Datensatz.

• Automatisierte Testsuite: 35 pytest-Tests, die die HTTP-Oberfläche, Tool-Registrierung, Request-Payload-Formen und Client-Schutzmechanismen abdecken.

Related MCP server: Zoho CRM MCP Server

📁 Repository-Struktur

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

⚙️ Einrichtung & Installation

1. Voraussetzungen

• Python 3.10+

• Eine Zoho-CRM-API-Console-App (Zoho API Console)

  • Client-Typ: Serverbasierte Anwendungen

  • Redirect-URI: http://localhost:8000/auth/callback (oder Ihre Deployment-Callback-URL)

2. Umgebungseinrichtung

cp .env.example .env

Mindestkonfiguration:

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

Alle unterstützten Variablen finden Sie in .env.example, einschließlich Genehmigungs-Gate, OAuth-Scope-Override, Ratenlimit- und Timeout-Einstellungen.

Arbeiten Sie mit mehr als einem Zoho-Konto? ZOHO_CLIENT_ID/ZOHO_CLIENT_SECRET sind optional. Lassen Sie sie leer und bitten Sie Claude, set_zoho_credentials(client_id, client_secret, redirect_uri?, data_center?) aufzurufen, oder übergeben Sie client_id/client_secret direkt an get_auth_url / exchange_auth_code. Das Wechseln der client_id löscht Tokens, die für das vorherige Konto gespeichert wurden, und vermeidet so Zohos invalid_client-Fehler durch die Wiederverwendung eines Refresh-Tokens, das für eine andere App ausgestellt wurde.

3. Abhängigkeiten installieren

pip install -r requirements.txt

🚀 Ausführen & Bereitstellen

Option A: Lokaler FastAPI-Webserver

python server.py

Oder direkt mit Uvicorn:

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

Sobald der Server läuft:

• Web-Dashboard: http://localhost:8000/

• Swagger-Dokumentation: http://localhost:8000/docs

• Health-Check: http://localhost:8000/health

• MCP-Endpunkt: http://localhost:8000/mcp

Option B: Lokales STDIO

python server.py --stdio

Option C: Cloud-Deployment (Render, Railway, Docker, AWS, Heroku)

• Startbefehl: uvicorn server:app --host 0.0.0.0 --port $PORT

• Health-Check-Pfad: /health

• Umgebungsvariablen: ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET, ZOHO_REDIRECT_URI, ZOHO_DATA_CENTER und ZOHO_TOKEN_ENCRYPTION_KEY setzen (damit Tokens Neustarts auf flüchtigen Dateisystemen überleben).

🖥️ Claude-Desktop-Integration

Modus 1: HTTP-/Remote-MCP-Verbindung

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

Modus 2: Lokale STDIO-Verbindung

{
  "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-Ablauf beim ersten Start

1. Server starten: python server.py

2. http://localhost:8000/auth/url öffnen oder Claude bitten, get_auth_url() auszuführen.

3. Die zurückgegebene URL öffnen, bei Zoho CRM anmelden und auf Accept klicken.

4. Zoho leitet zu /auth/callback?code=... weiter; der Server tauscht den Code aus und speichert verschlüsselte Tokens in ~/.zoho_crm_tokens.json.

🧩 Automatisierung erstellen: Das Workflow-Rezept

Zoho modelliert eine Workflow-Regel als Trigger plus Bedingungen, wobei jede Bedingung auf zuvor erstellte Aktions-Objekte verweist. Erstellen Sie sie in dieser Reihenfolge:

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="...")

Dasselbe Muster gilt mit create_email_notification_action, create_automation_task und create_webhook als Aktionsquelle.

🎯 Scoped-Session-Modus (Sicherheitsfilter)

Beschränken Sie jede Operation auf bestimmte Datensatz-IDs:

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

• REST: POST /scope/activate mit {"module": "Leads", "record_ids": ["123", "456"]}

• Deaktivieren: deactivate_scope() oder POST /scope/deactivate

Solange der Modus aktiv ist, werden Lesevorgänge in diesem Modul auf diese IDs gefiltert, und Schreibvorgänge auf andere IDs werden mit OUT_OF_SCOPE verweigert.

✅ Human-In-The-Loop-Genehmigungen (HITL)

Standardmäßig stellen destruktive Aktionen eine ausstehende Anfrage in die Warteschlange und geben eine request_id zurück, statt ausgeführt zu werden:

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.

• Prüfen: list_pending_approvals() oder GET /approvals

• Genehmigen & ausführen: approve_action(request_id="...") oder POST /approvals/{id}/approve

• Ablehnen & verwerfen: reject_action(request_id="...") oder POST /approvals/{id}/reject

• Gate vollständig deaktivieren: ZOHO_REQUIRE_APPROVAL=false setzen, damit diese Tools sofort ausgeführt werden.

Jede Anfrage, Genehmigung und Ablehnung wird im Aktivitätsprotokoll festgehalten.

📜 Aktivitätsprotokollierung

Auth-Ereignisse, ausgehende Zoho-API-Aufrufe, Funktionsausführungen und Genehmigungsentscheidungen werden als {timestamp, action, status, details}-Einträge aufgezeichnet – im Speicher gehalten und an ~/.zoho_crm_mcp_activity.log.jsonl angehängt.

• Abrufen: get_logs(limit=50, action=None, status=None) oder GET /logs

🔐 Token-Sicherheit

• Tokens werden im Ruhezustand verschlüsselt (Fernet/AES) in ~/.zoho_crm_tokens.json gespeichert.

• Der Schlüssel wird beim ersten Start automatisch in ~/.zoho_crm_mcp.key generiert (nur-Benutzer-Berechtigungen unter POSIX) oder explizit über ZOHO_TOKEN_ENCRYPTION_KEY gesetzt, um einen stabilen Schlüssel über Container-Neustarts hinweg zu gewährleisten.

• Tokens werden mit der client_id gekennzeichnet, die sie ausgestellt hat, und bei Nichtübereinstimmung verworfen. Das verhindert Zohos invalid_client-Fehler nach dem Wechseln von Konten.

• Ausgehende Aufrufe werden selbst gedrosselt (ZOHO_RATE_LIMIT_PER_SEC, Standard 10/Sek.) zusätzlich zum 429/5xx-Backoff.

🧪 Testen

pytest -v

Abgedeckt werden die HTTP-Oberfläche (/health, /, /auth/*, /scope/*, /approvals/*, /logs), die Registrierung aller 167 MCP-Tools, die exakten Request-Payloads für Workflows/Module/Notizen/Aufrufe/Webhooks/Merges/Locks, clientseitige Validierungs-Guards, Ratenlimit-Begrenzung und Zohos Erkennung von Teilfehlern.

Die Tests laufen vollständig offline – keine Zoho-Anmeldedaten erforderlich.

🛠️ MCP-Tool-Referenz

† Standardmäßig genehmigungspflichtig. Setzen Sie ZOHO_REQUIRE_APPROVAL=false, um sofort auszuführen.

* Die öffentliche REST-API von Zoho CRM bietet keinen Endpunkt für diese Operation – Blueprint-Erstellung, Deluge-Funktionsquellcode und Berichts-/Dashboard-Erstellung sind nur über die Benutzeroberfläche verfügbar oder gehören zum separaten Produkt Zoho Analytics. Diese Tools geben eine klare NOT_SUPPORTED_BY_ZOHO_API-Meldung zurück, die eine funktionierende Alternative nennt, anstatt gegen eine URL zu scheitern, die nicht existiert.

🧭 Alles erreichen, was nicht aufgeführt ist

Die API von Zoho ist größer als jeder handgeschriebene Wrapper. zoho_api_request deckt den Rest mit derselben Authentifizierungs-, Drosselungs- und Wiederholungsbehandlung ab:

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 wählt die URL-Basis: crm → {domain}/crm/v8 (Standard), bulk → {domain}/crm/bulk/v8, root → {domain}.