ZeptoMail Templates MCP

Un servidor MCP que permite a un agente de IA (opencode, Claude Desktop, Cursor, ...) inspeccionar y gestionar plantillas de correo electrónico en todos los Agentes de ZeptoMail de tu cuenta de Zoho.

Intencionadamente no envía correos electrónicos, no crea/elimina Agentes, no expone Tokens de Envío de Correo ni gestiona dominios. Solo lee la lista de Agentes y gestiona plantillas.

Inicio rápido (local, ~5 minutos)

1. Instala el servidor

npm i -g zeptomail-mcp

Esto te da un comando zeptomail-mcp en tu PATH. Omite esto si prefieres ejecutarlo desde un clon local de el repositorio (node /path/to/zeptomail-mcp/dist/src/server.js).

2. Crea una aplicación OAuth de Zoho

1. Abre la Consola de API de Zoho.

2. Crea una Aplicación basada en servidor:

   • Nombre del cliente: zeptomailmcp (sin guiones — Zoho los rechaza)

   • URL de página de inicio: cualquier cosa, p. ej. https://github.com/P4rthPat3l/zeptomail-mcp

   • URI de redirección autorizada: http://localhost:4567/callback

3. Anota el ID de cliente y el Secreto de cliente.

Un Self Client también funciona. No tiene campo de URI de redirección, así que en lugar del paso 2 usa su pestaña Generate Code (consulta Configuración de Self Client más abajo).

3. Obtén un token de actualización

ZOHO_CLIENT_ID=<your-client-id> ZOHO_CLIENT_SECRET=<your-secret> zeptomail-mcp-login

Tu navegador abre la pantalla de consentimiento de Zoho para los ámbitos Zeptomail.MailAgents.READ + Zeptomail.MailTemplates.All. Después de que lo apruebes, el script imprime un token de actualización.

Si estás ejecutando desde un clon local en lugar de una instalación global, este mismo comando es npm run login.

4. Configura tu host MCP

Puedes pasar las credenciales de Zoho en línea en la configuración del host, o cargarlas desde un archivo .env para que el archivo de configuración en sí mismo no contenga secretos. Ambas opciones funcionan; elige una.

Opción A — cargar desde un archivo .env (recomendado)

Pon los secretos en un archivo .env (añádelo a .gitignore — es una credencial):

# .env
ZOHO_CLIENT_ID=<your-client-id>
ZOHO_CLIENT_SECRET=<your-secret>
ZOHO_REFRESH_TOKEN=<your-refresh-token>
ZOHO_ACCOUNTS_URL=https://accounts.zoho.com

Luego apunta el servidor a él con --env-file. La ruta se resuelve relativa al directorio de trabajo del host; usa una ruta absoluta si no estás seguro.

opencode — opencode.json (o .opencode/opencode.json):

{
  "mcp": {
    "zeptomail": {
      "type": "local",
      "command": ["zeptomail-mcp", "--env-file=/absolute/path/to/.env"],
      "enabled": true
    }
  }
}

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "zeptomail": {
      "command": "zeptomail-mcp",
      "args": ["--env-file=/absolute/path/to/.env"]
    }
  }
}

Opción B — en línea en la configuración del host

opencode — opencode.json (o .opencode/opencode.json):

{
  "mcp": {
    "zeptomail": {
      "type": "local",
      "command": ["zeptomail-mcp"],
      "enabled": true,
      "environment": {
        "ZOHO_CLIENT_ID": "...",
        "ZOHO_CLIENT_SECRET": "...",
        "ZOHO_REFRESH_TOKEN": "...",
        "ZOHO_ACCOUNTS_URL": "https://accounts.zoho.com"
      }
    }
  }
}

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "zeptomail": {
      "command": "zeptomail-mcp",
      "env": {
        "ZOHO_CLIENT_ID": "...",
        "ZOHO_CLIENT_SECRET": "...",
        "ZOHO_REFRESH_TOKEN": "...",
        "ZOHO_ACCOUNTS_URL": "https://accounts.zoho.com"
      }
    }
  }
}

Ejecutar desde un clon local en lugar de una instalación global

Ejecuta el lanzador compilado directamente con node. Analiza --env-file de la misma manera que el comando global zeptomail-mcp, así que la bandera va después del script:

• opencode (Opción A archivo-env): ["node", "/absolute/path/to/zeptomail-mcp/dist/src/cli.js", "--env-file=/absolute/path/to/.env"]

• opencode (Opción B en línea): ["node", "/absolute/path/to/zeptomail-mcp/dist/src/cli.js"] + el bloque environment

• Claude Desktop: "command": "node", "args": [".../dist/src/cli.js", "--env-file=..."] (o solo [".../dist/src/cli.js"] con el bloque env)

5. Úsalo

Pide a tu agente que llame a las herramientas:

• "lista mis agentes de ZeptoMail"

• "encuentra la plantilla con alias team_invite"

• "muéstrame la plantilla OTP en el agente sandbox"

Related MCP server: Zoho Mail MCP Server

Configuración de Self Client

Un Self Client no tiene URI de redirección, así que zeptomail-mcp-login no puede capturar su callback. En su lugar:

1. Consola de API → Self Client → Generate Code.

2. Ámbito: Zeptomail.MailAgents.READ,Zeptomail.MailTemplates.All → CREATE.

3. Copia el código generado y cámbialo:

curl -X POST https://accounts.zoho.com/oauth/v2/token \
  -d "code=<generated code>" \
  -d "client_id=<client id>" \
  -d "client_secret=<client secret>" \
  -d "grant_type=authorization_code" \
  -d "redirect_uri=https://api-console.zoho.com/"

La respuesta JSON contiene refresh_token.

Herramientas

Las herramientas de escritura requieren ambas:

1. ZEPTOMAIL_MCP_ALLOW_WRITES=true en el entorno del servidor.

2. confirm=true en la llamada individual a la herramienta.

Cada escritura también requiere la agentKey exacta y el expectedAgentName de una llamada reciente a zeptomail_list_agents. La actualización/eliminación además requieren los valores de seguridad actuales de la plantilla (expectedModifiedTime, expectedTemplateName), de modo que una lectura obsoleta nunca pueda sobrescribir una edición más reciente.

Referencia de configuración

Todas las variables pueden proporcionarse como variables de entorno del proceso (establecidas por la configuración del host) o mediante un argumento --env-file=<ruta> al servidor (consulta Configura tu host MCP más arriba). Las variables de proceso tienen prioridad; el archivo solo completa las variables que no están establecidas.

Modo alojado (remoto) con OAuth 2.0 + PKCE

Para un endpoint MCP compartido/público, ejecuta con ZEPTOMAIL_MCP_TRANSPORT=http. El servidor se convierte en un servidor de autorización OAuth que actúa como proxy hacia Zoho como servidor de autorización ascendente:

MCP client ⇄ this MCP server (OAuth AS + resource server) ⇄ Zoho (upstream AS) ⇄ ZeptoMail API

ZEPTOMAIL_MCP_TRANSPORT=http \
ZEPTOMAIL_MCP_SERVER_URL=https://mcp.example.com \
ZEPTOMAIL_MCP_PORT=3006 \
ZEPTOMAIL_MCP_TOKEN_STORE=/var/lib/zeptomail-mcp/tokens.json \
node dist/src/server.js

• Los clientes descubren metadatos en /.well-known/oauth-protected-resource y /.well-known/oauth-authorization-server, se registran dinámicamente y dan su consentimiento en el navegador.

• El servidor redirige a Zoho con el desafío PKCE S256 del cliente y access_type=offline, intercambia el código con el secreto de cliente de Zoho del servidor y almacena un token de actualización de Zoho por cliente que nunca sale del servidor.

• Las herramientas de cada usuario operan en su propia cuenta de ZeptoMail.

Configuración del host (opencode):

{
  "mcp": {
    "zeptomail": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {}
    }
  }
}

Requisitos para el modo alojado: HTTPS (el SDK rechaza URLs de emisor no HTTPS excepto localhost), la URI de callback de Zoho registrada en la consola de API (https://mcp.example.com/callback) y un almacén de tokens persistente. Reiniciar el servidor invalida los tokens emitidos — los clientes vuelven a dar su consentimiento una vez.

Desarrollo

npm install
npm run typecheck
npm test
npm run build

Notas de seguridad

• El descubrimiento de Agentes es de solo lectura; no hay herramientas para crear Agentes, generar claves de API o acceder a Tokens de Envío de Correo.

• El MCP nunca envía correos electrónicos.

• ZEPTOMAIL_MCP_ALLOWED_AGENT_KEYS restringe qué Agentes puede tocar el MCP incluso cuando la cuenta OAuth puede ver más.

• El token de actualización es una credencial de larga duración: mantenlo en el lado del servidor, trátalo como una contraseña y revócalo en la consola de Zoho si alguna vez se filtra.