Zoho Campaigns MCP

Servidor MCP seguro para operar Zoho Campaigns API v1.1 desde Codex u otro cliente MCP.

Punto crítico: contactos devueltos

Zoho permite consultar contactos bounce por lista y consultar senthardbounce/sentsoftbounce por campaña, pero su documentación de producto indica expresamente que los contactos bounced no se pueden eliminar. No reciben campañas y no cuentan para el límite del plan. Este MCP respeta esa restricción y no inventa un endpoint de borrado que Zoho no publica.

Funciones

• OAuth 2.0 con refresh automático o access token temporal.
• Centros de datos .com, .eu, .in, .com.au, .jp, .ca y .sa.
• Catálogo de listas, contactos, campañas, tags, topics y workflows.
• Consulta agregada de bounced contacts en todas las listas.
• Consulta de hard/soft bounces por campaña.
• Desuscripción y Do-Not-Mail con confirmación explícita.
• Llamada catalogada y request v1.1 avanzado para mantener cobertura de endpoints nuevos.
• Confirmación literal para operaciones destructivas.
• Los secretos nunca se devuelven mediante herramientas MCP.

Instalación

npm install
npm run check
Copy-Item .env.example .env

Complete .env con un refresh token recomendado o un access token temporal. La configuración incluida en .codex/config.toml carga este archivo automáticamente al iniciar el MCP. El scope más simple para cobertura total es:

ZohoCampaigns.contact.ALL,ZohoCampaigns.campaign.ALL,ZohoCampaigns.workflow.READ,ZohoCampaigns.workflow.CREATE

Use privilegio mínimo si solo necesita lectura:

ZohoCampaigns.contact.READ,ZohoCampaigns.campaign.READ

Configuración en Codex

Compile y agregue el servidor por stdio:

npm run build
codex mcp add zoho-campaigns --env ZOHO_REGION=com --env ZOHO_CLIENT_ID=... --env ZOHO_CLIENT_SECRET=... --env ZOHO_REFRESH_TOKEN=... -- node C:\ruta\absoluta\zoho-campaigns-mcp\dist\index.js

También puede usar configuración de proyecto en .codex/config.toml:

[mcp_servers.zoho_campaigns]
command = "node"
args = ["--env-file=C:\\ruta\\absoluta\\zoho-campaigns-mcp\\.env", "C:\\ruta\\absoluta\\zoho-campaigns-mcp\\dist\\index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.zoho_campaigns.tools.zoho_campaigns_raw_request]
approval_mode = "prompt"

Ejecutar directamente desde GitHub con npx

El repositorio debe ser público y contener una versión/tag estable. No es necesario publicar el paquete en npm. Al iniciarse, npx descarga el código desde GitHub, ejecuta el script prepare y arranca el binario MCP por stdio.

{
  "mcpServers": {
    "zoho-campaigns": {
      "command": "npx",
      "args": ["-y", "github:Noche-Creativa/zoho-campaigns-mcp#v1.0.0"],
      "env": {
        "ZOHO_REGION": "com",
        "ZOHO_CLIENT_ID": "TU_CLIENT_ID",
        "ZOHO_CLIENT_SECRET": "TU_CLIENT_SECRET",
        "ZOHO_REFRESH_TOKEN": "TU_REFRESH_TOKEN"
      }
    }
  }
}

Sin el sufijo #v1.0.0, npx usará la rama predeterminada y podría incorporar cambios no revisados. Para credenciales sensibles, utilice el almacén seguro o las variables de entorno que ofrezca su cliente MCP cuando sea posible.

Uso sugerido

1. zoho_campaigns_auth_status
2. zoho_campaigns_bounced_contact_policy
3. zoho_campaigns_get_bounced_contacts
4. Para una campaña concreta: zoho_campaigns_get_campaign_bounces
5. Antes de cualquier mutación: solicitar confirmación al usuario.

Documentación oficial

• API overview
• OAuth y scopes
• List management
• Campaign management
• Restricción de bounced contacts