Servidor MCP de Zoho CRM (FastAPI + FastMCP)

Un servidor de Model Context Protocol (MCP) de nivel de producción construido con FastAPI + FastMCP que ofrece a Claude y otros clientes de IA un acceso completo y autenticado a la API REST de Zoho CRM v8 — desde la lectura de registros hasta el diseño de módulos y la creación de automatizaciones de flujos de trabajo.

167 herramientas MCP que cubren registros, COQL, diseño de esquemas, reglas de flujo de trabajo y sus acciones, webhooks, operaciones masivas, etiquetas, notas, correo electrónico, ajustes de seguridad e importación/exportación masiva — además de una vía genérica de escape zoho_api_request para cualquier cosa que Zoho exponga y que no tenga una herramienta dedicada.

🌟 Características principales

• Framework web FastAPI: Aplicación ASGI de alto rendimiento y lista para producción impulsada por Uvicorn.

• Transporte dual: Funciona como servidor MCP HTTP transmisible (para alojamiento remoto/en la nube) y como servidor MCP STDIO (para Claude Desktop local).

• Ciclo de vida completo de OAuth 2.0: Intercambio automático de código, manejador de redirección del navegador (/auth/callback), almacenamiento cifrado de tokens y un bucle en segundo plano que mantiene el token actualizado mientras el servidor está en ejecución.

• Credenciales configurables desde el chat: Proporciona un ID de cliente y secreto de Zoho desde el chat (set_zoho_credentials, o directamente en get_auth_url/exchange_auth_code) en lugar de .env — útil para cambiar de cuenta de Zoho sin reiniciar.

• Creación completa de automatizaciones: Construye reglas de flujo de trabajo de principio a fin: crea acciones de actualización de campos, notificaciones por correo, tareas y webhooks, y luego conéctalas a una regla con disparadores y criterios.

• Diseño de esquemas: Crea módulos personalizados (con los perfiles que Zoho exige), campos, listas de selección globales, diseños y canalizaciones de ventas.

• Modo de sesión con ámbito: Filtro de seguridad basado en ID (activate_scope) que restringe las operaciones a IDs de registro específicos.

• Aprobaciones con intervención humana (HITL): Las acciones destructivas ponen en cola una solicitud pendiente en lugar de ejecutarse. Se activa o desactiva con ZOHO_REQUIRE_APPROVAL.

• Registro de actividad estructurado: Cada evento de autenticación, llamada a la API y decisión de aprobación se registra como JSON, recuperable mediante get_logs() / GET /logs.

• Almacenamiento cifrado de tokens: Los tokens de OAuth se cifran en reposo (Fernet/AES), nunca en texto plano.

• Cliente de red resiliente: Cliente httpx agrupado con renovación y reintento automáticos ante 401, retroceso controlado ante 429, reintento exponencial ante errores 5xx, limitador de velocidad de salida y detección de fallos parciales en las respuestas por registro de Zoho.

• Suite de pruebas automatizada: 35 pruebas pytest que cubren la superficie HTTP, el registro de herramientas, las formas de las cargas útiles de solicitudes y las salvaguardas del cliente.

Related MCP server: Zoho CRM MCP Server

📁 Estructura del repositorio

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

⚙️ Configuración e instalación

1. Requisitos previos

• Python 3.10+

• Una aplicación de la consola de API de Zoho CRM (Consola de API de Zoho)

  • Tipo de cliente: Aplicaciones basadas en servidor

  • URI de redirección: http://localhost:8000/auth/callback (o la URL de devolución de llamada de tu despliegue)

2. Configuración del entorno

cp .env.example .env

Configuración mínima:

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

Consulta .env.example para conocer todas las variables admitidas, incluidos el control de aprobaciones, la anulación del ámbito de OAuth, el límite de velocidad y los ajustes de tiempo de espera.

¿Trabajas con más de una cuenta de Zoho? ZOHO_CLIENT_ID/ZOHO_CLIENT_SECRET son opcionales. Déjalos en blanco y pide a Claude que llame a set_zoho_credentials(client_id, client_secret, redirect_uri?, data_center?), o pasa client_id/client_secret directamente a get_auth_url / exchange_auth_code. Cambiar de client_id borra los tokens guardados de la cuenta anterior, lo que evita el error invalid_client de Zoho por reutilizar un token de actualización emitido para otra aplicación.

3. Instalar dependencias

pip install -r requirements.txt

🚀 Ejecución y despliegue

Opción A: Servidor web FastAPI local

python server.py

O directamente con Uvicorn:

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

Una vez en ejecución:

• Panel web: http://localhost:8000/

• Documentación Swagger: http://localhost:8000/docs

• Comprobación de estado: http://localhost:8000/health

• Endpoint MCP: http://localhost:8000/mcp

Opción B: STDIO local

python server.py --stdio

Opción C: Despliegue en la nube (Render, Railway, Docker, AWS, Heroku)

• Comando de inicio: uvicorn server:app --host 0.0.0.0 --port $PORT

• Ruta de comprobación de estado: /health

• Variables de entorno: define ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET, ZOHO_REDIRECT_URI, ZOHO_DATA_CENTER y ZOHO_TOKEN_ENCRYPTION_KEY (para que los tokens sobrevivan a los reinicios en sistemas de archivos efímeros).

🖥️ Integración con Claude Desktop

Modo 1: Conexión MCP HTTP / remota

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

Modo 2: Conexión STDIO local

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

🔑 Flujo de OAuth en el primer uso

1. Inicia el servidor: python server.py

2. Abre http://localhost:8000/auth/url, o pide a Claude que ejecute get_auth_url().

3. Abre la URL devuelta, inicia sesión en Zoho CRM y haz clic en Aceptar.

4. Zoho redirige a /auth/callback?code=...; el servidor intercambia el código y guarda los tokens cifrados en ~/.zoho_crm_tokens.json.

🧩 Creación de automatizaciones: la receta del flujo de trabajo

Zoho modela una regla de flujo de trabajo como un disparador más condiciones, donde cada condición apunta a objetos de acción creados previamente. Créalos en ese orden:

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

El mismo patrón se aplica con create_email_notification_action, create_automation_task y create_webhook como fuente de la acción.

🎯 Modo de sesión con ámbito (filtro de seguridad)

Restringe cada operación a IDs de registro específicos:

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

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

• Desactivar: deactivate_scope() o POST /scope/deactivate

Mientras esté activo, las lecturas de ese módulo se filtran a esos IDs, y las escrituras a cualquier otro ID se rechazan con OUT_OF_SCOPE.

✅ Aprobaciones con intervención humana (HITL)

De forma predeterminada, las acciones destructivas ponen en cola una solicitud pendiente y devuelven un request_id en lugar de ejecutarse:

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.

• Revisar: list_pending_approvals() o GET /approvals

• Aprobar y ejecutar: approve_action(request_id="...") o POST /approvals/{id}/approve

• Rechazar y descartar: reject_action(request_id="...") o POST /approvals/{id}/reject

• Desactivar el control por completo: define ZOHO_REQUIRE_APPROVAL=false para que estas herramientas se ejecuten de inmediato.

Cada solicitud, aprobación y rechazo se registra en el registro de actividad.

📜 Registro de actividad

Los eventos de autenticación, las llamadas salientes a la API de Zoho, las ejecuciones de funciones y las decisiones de aprobación se registran como entradas {timestamp, action, status, details} — se mantienen en memoria y se añaden a ~/.zoho_crm_mcp_activity.log.jsonl.

• Recuperar: get_logs(limit=50, action=None, status=None) o GET /logs

🔐 Seguridad de los tokens

• Los tokens se cifran en reposo (Fernet/AES) en ~/.zoho_crm_tokens.json.

• La clave se genera automáticamente en ~/.zoho_crm_mcp.key en el primer uso (con permisos solo para el usuario en POSIX), o se define explícitamente mediante ZOHO_TOKEN_ENCRYPTION_KEY para una clave estable entre reinicios del contenedor.

• Los tokens se etiquetan con el client_id que los emitió y se descartan si no coinciden, lo que evita el error invalid_client de Zoho después de cambiar de cuenta.

• Las llamadas salientes se autolimitan (ZOHO_RATE_LIMIT_PER_SEC, 10/seg por defecto) además del retroceso ante errores 429/5xx.

🧪 Pruebas

pytest -v

Cubren la superficie HTTP (/health, /, /auth/*, /scope/*, /approvals/*, /logs), el registro de las 167 herramientas MCP, las cargas útiles de solicitud exactas enviadas para flujos de trabajo/módulos/notas/llamadas/webhooks/fusiones/bloqueos, las salvaguardas de validación del lado del cliente, el ajuste del límite de velocidad y la detección de fallos parciales de Zoho.

Las pruebas se ejecutan completamente sin conexión — no se requieren credenciales de Zoho.

🛠️ Referencia de herramientas MCP

† Aprobación requerida por defecto. Establece ZOHO_REQUIRE_APPROVAL=false para ejecutar de inmediato.

* La API REST pública de Zoho CRM no tiene endpoint para esta operación: la creación de blueprints, el código fuente de funciones Deluge y la creación de informes/paneles son solo de interfaz o pertenecen al producto independiente Zoho Analytics. Estas herramientas devuelven un mensaje claro NOT_SUPPORTED_BY_ZOHO_API que indica una alternativa viable, en lugar de fallar contra una URL que no existe.

🧭 Acceder a cualquier cosa no listada

La API de Zoho es más amplia que cualquier envoltorio escrito a mano. zoho_api_request cubre el resto con el mismo manejo de autenticación, limitación de velocidad y reintentos:

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 selecciona la base de la URL: crm → {domain}/crm/v8 (predeterminado), bulk → {domain}/crm/bulk/v8, root → {domain}.