GoContact MCP

Servidor MCP que conecta Claude con la API de GoContact para consultar leads, ventas y actividad del contact center en lenguaje natural.

"¿Cuántos leads cargó cada proveedor la semana pasada y cuántos acabaron en venta?" Antes: esperar días a un Excel. Ahora: una pregunta.

El problema

Los datos del contact center (leads cargados, llamadas, ventas por agente y por proveedor) llegaban en informes preparados a mano. Tardaban días, y sin ellos no se podía optimizar la inversión en captación ni el trabajo del equipo de ventas.

Related MCP server: dbt Semantic Layer MCP Server

La solución

Un servidor MCP de solo lectura que:

1. Pide los informes al Report Designer de GoContact por API.

2. Los descarga, limpia y cruza entre sí (leads ↔ llamadas ↔ ventas).

3. Aplica las reglas de negocio del equipo (qué es una venta, qué llamada está contestada, a qué proveedor pertenece cada lead).

4. Se los entrega a Claude, que responde preguntas, genera informes y detecta desviaciones.

flowchart LR
    U[Equipo de marketing] -->|pregunta| C[Claude]
    C -->|herramientas MCP| S[GoContact MCP]
    S -->|generateReport / download| G[(API GoContact)]
    S -->|contacts, databases, owners| G
    R[business_rules.json] --> S
    S -->|datos limpios y cruzados| C
    C -->|respuesta, tabla, informe| U

Herramientas

Lo importante no es el código: son las definiciones

Conectar una API es la parte fácil. Lo difícil fue que los números cuadraran con el cierre manual. Algunas decisiones que salieron de validar contra datos reales (más detalle en docs/reglas-de-negocio.md):

• Una llamada con tiempo de conversación no siempre está contestada. Casi la mitad de las llamadas marcadas "No Contactado" tenían segundos de conversación (buzones, locuciones). Contestada = outcome válido y conversación.

• Venta segura = tres condiciones a la vez en el script: grupo "Venta", producto válido y gestión de contratación válida.

• El proveedor se asigna por el id de formulario, no por el campo "proveedor", que viene escrito de mil maneras. El campo solo se usa como respaldo.

• Las llamadas transferidas tienen varios tramos. Se conservan todos (cada uno es trabajo de un agente) y solo se eliminan las filas duplicadas.

• La fecha de carga del lead no es la fecha de creación de la base. Si el informe no la trae, se pide a la API de contactos.

Todas estas reglas están en config/business_rules.json, fuera del código, para que alguien de negocio pueda cambiarlas sin tocar Python.

Instalación

git clone https://github.com/marinscada/gocontact-mcp.git
cd gocontact-mcp
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env                                         # credenciales y plantillas
cp config/business_rules.example.json config/business_rules.json   # tus reglas de negocio

Preparar GoContact

1. Crea un usuario de servicio con acceso a las campañas y colas que quieras consultar.

2. En el Report Designer, crea tres plantillas: Contact state by last load date (leads), Calls With Script (ventas) y All Calls (llamadas). Incluye Contact ID, agente y UUID de llamada. No incluyas datos personales (nombre, teléfono, email, DNI): no hacen falta.

3. Pon sus templateId en .env.

4. Ejecuta columnas_informe y ajusta el bloque columnas de business_rules.json a las cabeceras reales.

Uso local con Claude Desktop

En claude_desktop_config.json:

{
  "mcpServers": {
    "gocontact": {
      "command": "/ruta/a/.venv/bin/python",
      "args": ["/ruta/a/gocontact-mcp/server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GOCONTACT_BASE": "https://TU-DOMINIO.gocontact.es/poll",
        "GOCONTACT_USER": "usuario_servicio@dominio",
        "GOCONTACT_PASS": "...",
        "GC_TEMPLATE_LEADS": "123",
        "GC_TEMPLATE_VENTAS": "124",
        "GC_TEMPLATE_LLAMADAS": "125"
      }
    }
  }
}

Uso remoto (para todo el equipo)

Con MCP_TRANSPORT=streamable-http, alojado con HTTPS y OAuth delante, y dado de alta como conector personalizado en Claude.

Seguridad

• Solo lectura: ninguna herramienta modifica datos en GoContact.

• Sin datos personales: las plantillas se diseñan sin ellos y las respuestas trabajan con IDs y agregados.

• Credenciales fuera del código: van en variables de entorno; .env y business_rules.json están en .gitignore.

• Escucha en local por defecto (HOST=127.0.0.1). El servidor no incluye autenticación propia: para exponerlo en remoto, ponlo siempre detrás de un proxy con OAuth.

Rendimiento

• Los informes se lanzan en paralelo y se descargan cuando están listos (GoContact los genera en diferido).

• Se guardan 30 minutos en caché, así que preguntas encadenadas sobre el mismo mes son instantáneas.

• El token se renueva solo antes de caducar (24 h).

Tests

pip install pytest
pytest

Prueban las reglas de negocio (asignación de proveedor, venta segura, llamada contestada, fechas) sin llamar a GoContact.

Próximos pasos

• Mover la caché a Redis para el despliegue remoto con varios usuarios.

• Alertas automáticas cuando un proveedor cae por debajo de su conversión media.

• Tests de integración con CSV de ejemplo anonimizados.

Sobre este proyecto

Construido por Andrea (Growth Marketing) con Claude como compañero de código, para dejar de depender de informes manuales y tomar decisiones con datos al momento.

Licencia MIT.