zoho-multi-mcp

Un servidor MCP (Model Context Protocol) que conecta asistentes de IA como Claude a tus cuentas de Zoho Mail. Lee, envía, busca, responde y elimina correos electrónicos directamente desde tu flujo de trabajo de IA — y ejecuta cualquier número de buzones de Zoho desde un único proceso ligero, en lugar de un proceso por buzón.

Esto es un fork de FujiwaraChoki/zoho-mail-mcp (con licencia MIT, ver LICENSE) con soporte multi-cuenta añadido. Todo el crédito del servidor original de una sola cuenta corresponde al autor del proyecto original.

Por qué existe este fork

Si ejecutas varios buzones de Zoho a través de MCP (un equipo, un conjunto de remitentes específicos de proyectos, lo que sea), la configuración natural es un proceso de servidor por buzón. Eso funciona, pero cada proceso paga la misma sobrecarga fija de memoria del runtime Bun/V8 — aproximadamente 75-85 MB de RSS — sin importar lo pequeño o inactivo que sea el buzón. Tres buzones cuestan tres veces esa base sin ningún beneficio, ya que el estado real por cuenta (un token OAuth, una caché de carpetas) es mínimo.

Este fork añade un modo multi-cuenta opcional: un solo proceso puede servir varias cuentas de Zoho, ya sea como un único endpoint donde quien llama especifica qué cuenta usar en cada llamada, o — la opción más segura para una configuración existente — como varios listeners en sus propios puertos fijos, comportándose cada uno exactamente como un servidor normal de una sola cuenta. Medido en producción: 3 procesos separados de una sola cuenta con ~230 MB de RSS combinado, consolidados en un solo proceso con ~90 MB de RSS sirviendo los mismos 3 buzones. Todo lo que está por debajo de la sección «Modo multi-cuenta» no ha cambiado respecto al proyecto original y funciona exactamente como siempre si solo necesitas un buzón.

Related MCP server: Mailing Manager MCP

Herramientas

Configuración

1. Crear un cliente de API de Zoho

1. Ve a la Zoho API Console (usa .com para el centro de datos de EE. UU.)

2. Haz clic en Add Client > Self Client

3. Anota tu Client ID y Client Secret

2. Generar un Refresh Token

Ejecuta el asistente de configuración interactivo:

bun run setup.ts

O manualmente:

1. En el Self Client, genera un código de concesión (grant code) con estos ámbitos (scopes):

   ZohoMail.accounts.READ,ZohoMail.folders.READ,ZohoMail.messages.READ,ZohoMail.messages.CREATE,ZohoMail.messages.DELETE

2. Establece la duración en 10 minutos, añade una descripción y haz clic en Create

3. Copia el código generado e intercámbialo usando el script de configuración

3. Verificar las credenciales

ZOHO_CLIENT_ID=your_id ZOHO_CLIENT_SECRET=your_secret ZOHO_REFRESH_TOKEN=your_token bun run setup.ts --verify

4. Configurar tu cliente MCP

Una sola cuenta — Claude Code (~/.claude.json)

{
  "mcpServers": {
    "zoho-mail": {
      "command": "bun",
      "args": ["run", "/path/to/zoho-multi-mcp/src/index.ts"],
      "env": {
        "ZOHO_CLIENT_ID": "your_client_id",
        "ZOHO_CLIENT_SECRET": "your_client_secret",
        "ZOHO_REFRESH_TOKEN": "your_refresh_token",
        "ZOHO_DATACENTER": "eu"
      }
    }
  }
}

La misma estructura para claude_desktop_config.json de Claude Desktop.

Modo multi-cuenta

Repite cualquiera de los pasos anteriores una vez por cada cuenta de Zoho que quieras ejecutar a través de este servidor y, a continuación, elige uno de los dos modos.

Modo A — un único endpoint, quien llama elige la cuenta

Establece ZOHO_ACCOUNTS_JSON como un array JSON de cuentas e inicia el servidor con ZOHO_HTTP_PORT como siempre (o stdio). Cada herramienta gana un campo account obligatorio (un enum de cadenas con los ids que proporcionaste), y cada llamada debe indicar para qué cuenta es.

export ZOHO_ACCOUNTS_JSON='[
  {"id": "work", "clientId": "...", "clientSecret": "...", "refreshToken": "..."},
  {"id": "personal", "clientId": "...", "clientSecret": "...", "refreshToken": "..."}
]'
export ZOHO_HTTP_PORT=8010
bun run src/index.ts

Adecuado cuando tu cliente MCP acepta un argumento account explícito en cada llamada y quieres una única URL para configurar.

Modo B — un proceso, varios listeners de cuenta fija

Establece ZOHO_ACCOUNTS_JSON como arriba, y configura ZOHO_MULTI_PORT_JSON para vincular cada cuenta a su propio puerto. Cada listener se comporta como un auténtico servidor de una sola cuenta — sin campo account en ninguna herramienta, byte-idéntico a una configuración normal de una sola cuenta en ese puerto.

export ZOHO_ACCOUNTS_JSON='[
  {"id": "work", "clientId": "...", "clientSecret": "...", "refreshToken": "..."},
  {"id": "personal", "clientId": "...", "clientSecret": "...", "refreshToken": "..."}
]'
export ZOHO_MULTI_PORT_JSON='[
  {"id": "work", "port": 8010, "name": "zoho-mail-work"},
  {"id": "personal", "port": 8011, "name": "zoho-mail-personal"}
]'
bun run src/index.ts

Este es el modo a usar al migrar una configuración multi-proceso EXISTENTE: apunta la configuración de tu cliente MCP a los mismos puertos que ya usa, inicia este único proceso en lugar de los varios que solías ejecutar, y nada más necesita cambiar. name es opcional y solo afecta a las etiquetas de las líneas de log.

Ninguno de los dos modos es obligatorio — omite tanto ZOHO_ACCOUNTS_JSON como ZOHO_MULTI_PORT_JSON y el servidor se comporta exactamente igual que el proyecto original de una sola cuenta, leyendo ZOHO_CLIENT_ID/ZOHO_CLIENT_SECRET/ZOHO_REFRESH_TOKEN directamente.

Variables de entorno

Características

• OAuth2 con auto-refresh - los tokens se renuevan automáticamente, sin intervención manual, con caché por cuenta en el modo multi-cuenta

• Limitación de velocidad - limitador de velocidad integrado de ventana deslizante (30 req/min) para mantenerse dentro de los límites de la API de Zoho

• Reintento en 401 - renueva automáticamente el token y reintenta en fallos de autenticación

• HTML a texto plano - el contenido del correo se convierte a texto plano limpio para el consumo de IA

• Multi-cuenta, bajo consumo de memoria - ver «Por qué existe este fork» arriba

Requisitos

• Runtime de Bun

• Una o más cuentas de Zoho Mail con acceso a la API

Licencia

MIT (c) 2026 Sami Hindi — ver LICENSE. Las adiciones multi-cuenta/multi-puerto de este fork se publican bajo la misma licencia.