# 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

```powershell
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:

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

Use privilegio mínimo si solo necesita lectura:

```text
ZohoCampaigns.contact.READ,ZohoCampaigns.campaign.READ
```

## Configuración en Codex

Compile y agregue el servidor por `stdio`:

```powershell
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`:

```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`.

```json
{
  "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](https://www.zoho.com/campaigns/help/developers/)
- [OAuth y scopes](https://www.zoho.com/campaigns/help/developers/access-token.html)
- [List management](https://www.zoho.com/campaigns/help/developers/list-management.html)
- [Campaign management](https://www.zoho.com/campaigns/help/developers/campaign-management.html)
- [Restricción de bounced contacts](https://help.zoho.com/portal/en/kb/campaigns/faqs/contact-management/articles/contact-management-faq)