Cómo conectar Chatwoot a Gemini vía MCP

💡 ¿Sin instalación? Usa cloud.anythingmcp.com directamente. Inicia sesión, pulsa Connectors → Chatwoot, pega tus credenciales, genera una MCP API key y listo. Sin Docker, sin git clone, sin servidor local.

Chatwoot + Gemini

Chatwoot, la bandeja de soporte omnicanal, en la nube o autoalojada: conversaciones y mensajes de WhatsApp, e-mail, chat web y canales sociales, contactos, etiquetas, agentes, equipos, respuestas predefinidas e informes de soporte (primera respuesta, tiempos de resolución y de respuesta). Las respuestas, notas privadas y nuevas conversaciones están incluidas, pero desactivadas al instalar.

Requisitos previos

Las instrucciones de configuración completas están incluidas en el conector (visibles en el store al seleccionarlo). Las variables de entorno requeridas:

CHATWOOT_URL, CHATWOOT_API_TOKEN, CHATWOOT_ACCOUNT_ID

Paso 1 — Obtener credenciales

La configuración lleva unos 2 minutos. Necesitas una cuenta de Chatwoot, en Chatwoot Cloud o autoalojada, y el access token del usuario con el que debe trabajar la IA.

1. Inicia sesión en Chatwoot con ese usuario. Los agentes solo ven las conversaciones de las bandejas de las que son miembros y no pueden leer informes, así que para tener la visión completa usa un administrador.
2. Haz clic en tu avatar, después en Profile Settings, y copia el Access Token del final de la página en CHATWOOT_API_TOKEN. No caduca; puedes restablecerlo en la misma página.
3. Pon en CHATWOOT_URL la dirección con la que abres Chatwoot: https://app.chatwoot.com en Chatwoot Cloud, o tu propio dominio, por ejemplo https://chat.example.com, si lo alojas tú. Sin ruta, sin /app, sin /api.
4. Pon en CHATWOOT_ACCOUNT_ID el número que aparece después de /app/accounts/ en la barra de direcciones: https://app.chatwoot.com/app/accounts/3/dashboard significa 3.
5. Instala el conector y ejecuta chatwoot_get_profile: muestra el usuario detrás del token, su rol y todas las cuentas a las que llega el token, con su id.

Token de cuenta, no Platform API: el token de una Platform App de un super admin (/platform/api) no sirve aquí. El conector usa la Application API de Chatwoot de una cuenta.

Autoalojado detrás de nginx: el token viaja en la cabecera api_access_token, y nginx descarta las cabeceras con guion bajo si no se configura underscores_in_headers on;. Se nota como un 401 en cada llamada aunque el token sea correcto. Un Chatwoot autoalojado que solo vive en una red privada no es accesible desde AnythingMCP Cloud; en ese caso usa un AnythingMCP autoalojado dentro de esa red.

Qué lee: la cuenta y el usuario detrás del token; tus bandejas (WhatsApp, e-mail, widget web, API, Instagram, Telegram y más) con sus miembros; agentes y administradores con su disponibilidad; equipos y sus miembros; etiquetas, respuestas predefinidas (canned responses) y definiciones de atributos personalizados; conversaciones con estado, prioridad, bandeja, etiquetas, contacto, agente asignado y equipo, como lista, como recuento o con filtros como creadas después de una fecha y asignadas a un agente; los mensajes de una conversación, incluidas notas privadas y adjuntos; contactos por nombre, e-mail, teléfono o identificador, con todas sus conversaciones en cualquier bandeja; y los informes de soporte: totales de un periodo junto al periodo anterior, una métrica a lo largo del tiempo, agentes, bandejas o equipos comparados y lo que está abierto y sin atender ahora mismo. Los secretos de canal de las bandejas y el access token del propio usuario se eliminan de las respuestas.

Horas y cifras: las horas de conversaciones y mensajes y los periodos de los informes son marcas de tiempo Unix en segundos (UTC), y la IA las convierte antes de darte una hora. La primera respuesta, el tiempo de resolución y el tiempo de respuesta de los informes están en segundos.

Pregunta antes de cada cambio: chatwoot_set_conversation_labels. Chatwoot sustituye la lista completa de etiquetas de una conversación, así que la IA lee primero las etiquetas actuales y las envía junto con la nueva (o sin la que hay que quitar). Las etiquetas tienen que existir ya en la cuenta. La IA te muestra la conversación y la nueva lista y espera tu sí.

Desactivadas al instalar: chatwoot_send_message (una respuesta, o una nota privada que solo ven los agentes) y chatwoot_create_conversation. Una respuesta o un primer mensaje llega al cliente al instante por WhatsApp, e-mail o chat, así que un administrador las activa a propósito. Incluso entonces la IA te muestra el texto y el destinatario y espera tu sí. En las bandejas de WhatsApp Cloud API, el texto libre solo llega a un contacto dentro de las 24 horas siguientes a su último mensaje; fuera de esa ventana Chatwoot necesita una plantilla aprobada, que este conector no envía.

Límites: las conversaciones llegan de 25 en 25 por página, los contactos de 15 en 15 y los mensajes de 20 en 20, así que la IA va pasando páginas; para una simple cifra cuenta en lugar de listar. Los informes y las estadísticas en vivo necesitan el token de un administrador.

Errores comunes: 401 significa un token incorrecto o restablecido, o nginx descartando la cabecera. Un 404 en todas las llamadas suele indicar un CHATWOOT_URL o un CHATWOOT_ACCOUNT_ID incorrecto; un 404 en una sola conversación indica un id que este usuario no puede ver. Los informes responden 401 o 403 a los agentes que no son administradores.

El conector no usa la Platform API, no envía plantillas de WhatsApp, no resuelve, reasigna ni borra conversaciones existentes y no edita ni borra contactos.

Paso 2 — Instalar el adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Paso 3 — Añadir el conector en Gemini

La URL de tu servidor: en AnythingMCP abre MCP Servers → el servidor donde está este conector y copia su URL (https://cloud.anythingmcp.com/mcp/…). Úsala donde esta guía muestra YOUR_SERVER_ID.

Gemini CLI lee los servidores MCP de ~/.gemini/settings.json (en Windows, %USERPROFILE%\.gemini\settings.json). Añade:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una clave de API MCP en AnythingMCP en MCP Servers → tu servidor → API keys y pégala en lugar de YOUR_MCP_API_KEY.
2. Guarda el archivo y reinicia gemini.
3. Ejecuta /mcp dentro de Gemini CLI (o gemini mcp list en tu terminal): anythingmcp debería aparecer como conectado.
4. Empieza a escribir prompts: Gemini CLI ya puede llamar a las herramientas de Chatwoot.

Herramientas disponibles

Ejemplos de prompts

• "¿Cuántas conversaciones abiertas están sin asignar ahora mismo, y qué agentes tienen chats sin atender?"
• "Lee la conversación 1284 y resúmeme qué quiere el cliente y qué le hemos prometido ya."
• "Busca el contacto [email protected] y lista todas sus conversaciones por WhatsApp y e-mail."
• "Compara a nuestros agentes en los últimos 30 días: conversaciones atendidas, tiempo de primera respuesta y tiempo de resolución."
• "Añade la etiqueta reembolso a la conversación 1284 sin quitar las demás. Enséñame antes la nueva lista."

FAQ

¿Dónde busca Gemini CLI los servidores MCP? En ~/.gemini/settings.json para tu usuario, o en .gemini/settings.json dentro de un proyecto. gemini mcp list muestra cada servidor y si se conecta.

Siguientes pasos

• Página del conector
• Conectar a Claude
• Conectar a ChatGPT