GoHighLevel MCP Server

Un servidor de Model Context Protocol que otorga a un agente LLM control operativo de un CRM de GoHighLevel — 114 herramientas en 24 módulos, que abarcan contactos, pipelines, calendarios, mensajería, facturación y pagos a través de la API v2 de GoHighLevel.

El problema

GoHighLevel es el sistema de registro para una agencia pequeña: cada cliente, cada reserva, cada factura. El trabajo que de verdad consume el día no es una acción aislada de CRM, sino la costura entre las acciones: se confirma una sesión, así que alguien tiene que crear la oportunidad, pasarla a la etapa correcta del pipeline, reservar el hueco de calendario con el contacto adecuado, redactar la factura y dejar una nota. Cada paso son treinta segundos de clics, y la secuencia se repite varias veces por semana.

Esa secuencia es exactamente lo que puede hacer un agente, si puede llegar hasta el CRM. Este servidor es ese acceso: expone GoHighLevel como herramientas tipadas y anotadas para que un agente realice toda la cadena a partir de una sola frase de instrucción, mientras que los pasos destructivos y los que tienen visibilidad externa siguen quedando a la vista para su aprobación.

Related MCP server: GoHighLevel MCP Server

Arquitectura

Los módulos de herramientas se registran contra un único McpServer sobre stdio. Todo lo enruta a una única función ghlRequest(), que gestiona la autenticación, la cabecera obligatoria Version, el ensamblado de la cadena de consulta y el modelado de errores. Los módulos se pueden activar o desactivar en el arranque mediante GHL_DISABLED_MODULES — algo más relevante de lo que parece, porque 114 definiciones de herramientas suponen una porción significativa de la ventana de contexto de un agente antes de que este haya leído una sola palabra de la solicitud del usuario. Un despliegue que solo hace reservas puede registrar seis módulos y omitir el resto.

  MCP host (Claude Desktop / Claude Code)
          | stdio (JSON-RPC)
  +-------v--------------------------------------------+
  |  index.ts   MODULES registry, GHL_DISABLED_MODULES  |
  +-------+--------------------------------------------+
          |
  +-------v-----+ +---------------+ +-----------+ ......  24 modules
  |  contacts   | | opportunities | | invoices  |
  +-------+-----+ +-------+-------+ +-----+-----+
          |               |               |
          |               |         +-----v--------------+
          |               |         | billing-helpers.ts |
          |               |         |  businessDetails   |
          |               |         |  contactDetails    |
          |               |         |  sender resolution |
          |               |         +-----+--------------+
          +-------+-------+---------------+
                  |
        +---------v----------------------------+
        |  client.ts  ghlRequest()             |
        |   Bearer token + Version header      |
        |   status-specific error hints        |
        +---------+----------------------------+
                  |
          services.leadconnectorhq.com

Cada herramienta de escritura lleva anotaciones MCP — 114 están marcadas como destructiveHint, y las herramientas ghl_send_message y ghl_send_invoice se marcan como hacia afuera porque contactan con clientes reales. El host muestra esas marcas antes de aprobar una llamada, que es la diferencia entre un agente que redacta una factura y un agente que se la envía a un cliente por accidente.

La parte realmente complicada

Crear una factura. El endpoint acepta bloques businessDetails y contactDetails, y la documentación no detalla bien ninguno de los dos: si pasas un contactId y un par de líneas de detalle, como sugieren los documentos, obtienes un error de validación que no nombra ningún campo. Ambos bloques son obligatorios al completo, y businessDetails.phoneNo y contactDetails.phoneNo son obligatorios — un contacto con email y sin teléfono no se puede facturar en absoluto.

Y lo que es peor, los valores tienen que coincidir con lo que produce la interfaz; si no, las facturas creadas por API tienen un aspecto diferente de las facturas creadas a mano: un logotipo distinto, condiciones de pago que faltan, numeración incorrecta. Esos valores por defecto no están en el perfil de ubicación del que cabría esperar; viven detrás de GET /invoices/settings, que es la misma fuente de la que la interfaz precarga la información.

src/tools/billing-helpers.ts resuelve ambos bloques para que las herramientas solo necesiten un contactId. Los detalles de empresa caen a través de cuatro niveles — argumento por llamada, GHL_BUSINESS_* (variables de entorno), ajustes de factura guardados, perfil de ubicación — y cada nivel rellena solo lo que el nivel superior dejó vacío. Los datos de contacto se obtienen y se estructuran, y el campo name cae sucesivamente al nombre completo, nombre + apellidos, nombre de empresa, email y teléfono; porque GoHighLevel rechaza un nombre vacío, y los registros reales del CRM a menudo carecen de uno. Ambas rutas lanzan un mensaje que indica el campo que falta y cómo suministrarlo, en lugar de mostrar el opaco error 422 de GHL. Cada búsqueda se memoiza por ubicación, de modo que un lote de diez facturas cuesta una única llamada de configuración, no diez.

Lo que haría de otra manera

1. No hay tests. 4.000 líneas y ninguno. La cadena de fallback de billing-helpers es lógica pura sobre datos de prueba — lo más fácil de testear del repositorio y lo más costoso de fastidiar, porque el error suele manifestarse como factura malformada enviada a un cliente.

2. No hay reintentos en el 429. ghlRequest le dice al que llama «limitado; reintenta tras un breve retardo» y luego no reintenta. La espera con backoff debería vivir en el cliente, no en el criterio del agente.

3. Los conoceslas son mapas mutables a nivel de módulo sin invalidación. Correcto para un servidor stdio que el host reinicia con libertad; incorrecto en cuanto esto corra como un proceso longevo, donde una edición de perfil comercial nunca sería recogida.

4. Las respuestas son siempre Record<string, unknown> en todo el código. GoHighLevel publica una especificación OpenAPI; generar tipos a partir de ella convertiría una clase de sorpresas de ejecutorunos Counter en errores de compilación.

5. 114 herramientas en un servidor son demasiadas. Los toggles de módulos son una solución de emergencia, no una solución real. La forma mejor es un conjunto pequeño de herramientas más un mecanismo de descubrimiento, para que el agente pague solo por lo que usa.

Configuración

Requiere Node 20+ y una cuenta de GoHighLevel.

1. Crear un token de integración privada

**Configuración → Integraciones privadas → Crear integración nueva. ** Activa los scopes que se correspondan con las herramientas que vayas a usar; como mínimo:

contacts.readonly, contacts.write, opportunities.readonly, opportunities.write, calendars.readonly, calendars/events.write, conversations.readonly, conversations/message.write, invoices.readonly, invoices.write, products.readonly, products.write, locations/customFields.readonly, workflows.readonly

Copia el token — empieza por pit-.

2. Localizar tu ID de ubicación

Configuración → Perfil de negocio, o extráelo de la URL del panel de control: .../location/<LOCATION_ID>/...

3. Compilar

git clone <this-repo>
cd ghl-mcp
npm install
npm run build

4. Registrar en un host MCP

{
  "mcpServers": {
    "gohighlevel": {
      "command": "node",
      "args": ["/absolute/path/to/ghl-mcp/dist/index.js"],
      "env": {
        "GHL_API_KEY": "pit-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}

Reinicia el host. Mira .env.example para conocer todas las variables permitidas, incluido el bloque de datos de la factura y los toggles de módulo.

Para probar el servidor sin host:

GHL_API_KEY=pit-... GHL_LOCATION_ID=... npm run inspect

Nota sobre «construir automatizaciones»

La API de GoHighLevel no puede crear la lógica de flujos de trabajo: el editor visual es el único sitio que lo permite. Lo compatible es construir el workflow una vez en la interfaz, encontrar su id con ghl_list_workflows y añadir contactos con ghl_add_contact_to_workflow.

Referencia de herramientas

Licencia

MIT — consulta LICENSE. Sin afiliación ni respaldo de GoHighLevel.