@aiwerk/mcp-server-ghl

Servidor MCP para la API de GoHighLevel (GHL), la plataforma de CRM y automatización de marketing que las agencias utilizan para gestionar los embudos de ventas, calendarios, conversaciones y campañas de sus clientes.

569 herramientas en 41 dominios, generadas a partir de la especificación oficial OpenAPI 3.0.0 de GHL.

Contacts       Opportunities   Conversations   Calendars      Invoices
Payments       Workflows       Campaigns       Forms          Surveys
Funnels        Blogs           Courses         Products       Store
Social Media   Ad Manager      SaaS API        Snapshots      Custom Fields

Por qué está generado

Cada endpoint, verbo HTTP, parámetro y nombre de campo proviene de la especificación oficial en lugar de documentación en prosa, por lo que la superficie de herramientas no puede desviarse de lo que GHL realmente acepta. Lo que la especificación no puede decirte —qué endpoints requieren un token de nivel de agencia en lugar de uno de ubicación, qué versión de API espera un endpoint, qué campos la documentación olvidó marcar como obligatorios— se superpone a mano. Consulta Particularidades de GHL que merece la pena conocer.

Related MCP server: GoHighLevel MCP Server

Instalación

npm install -g @aiwerk/mcp-server-ghl

Requiere Node.js 18 o superior.

Autenticación

Crea un Token de integración privada (PIT) en la ubicación de destino en Configuración > Integraciones privadas. Un PIT está limitado a una ubicación, no es una credencial de toda la agencia, y la mayoría de las herramientas necesitan saber en qué ubicación están actuando.

export GHL_PIT_TOKEN="your-private-integration-token"
export GHL_LOCATION_ID="your-location-id"

Uso

Claude Code

claude mcp add ghl \
  --env GHL_PIT_TOKEN=your-token \
  --env GHL_LOCATION_ID=your-location-id \
  -- npx -y @aiwerk/mcp-server-ghl

Claude Desktop

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["-y", "@aiwerk/mcp-server-ghl"],
      "env": {
        "GHL_PIT_TOKEN": "your-token",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}

Servicio alojado de AIWerk

Instálalo desde el catálogo en aiwerkmcp.com y añade tu token en la interfaz. No se requiere configuración local.

Funciones de seguridad

Ejecución en seco

export GHL_DRY_RUN=1

Cada escritura (POST/PUT/PATCH/DELETE) se detiene antes de llegar a GHL y devuelve una descripción de la solicitud que se habría enviado. Las lecturas siguen funcionando con normalidad.

Los endpoints exclusivos de agencia devuelven un error claro, no un 401 sin más

39 endpoints (instantáneas, la API SaaS, el intercambio de tokens OAuth de agencia, la creación de objetos personalizados) requieren un token de nivel de agencia. Un PIT de ubicación recibe un 401 simple de GHL para estos sin explicación en el cuerpo; el servidor sabe qué endpoints son estos y devuelve un mensaje que lo indica, en lugar de hacer que parezca un token malo o caducado.

locationId se rellena automáticamente

Un PIT ya está limitado a una ubicación, por lo que 430 de las 569 herramientas aceptan locationId (o altId/altType) como parámetro opcional; si el agente que llama no proporciona uno, el servidor recurre a GHL_LOCATION_ID. Esto también significa que una llamada a una herramienta no puede apuntar accidentalmente a la ubicación equivocada mediante un id copiado y pegado de otra cuenta, ya que el valor predeterminado siempre coincide con el ámbito del propio token.

Configuración

Reducir el conjunto de herramientas

Las 569 herramientas están registradas por defecto. Un cliente que prefiera una superficie más pequeña puede restringir el servidor a dominios específicos (los nombres de dominio están separados por guiones, p. ej. social-media-posting, ad-manager):

export GHL_ENABLED_TAGS="contacts,opportunities,conversations,calendars"

Los nombres de dominio desconocidos se notifican al iniciar en lugar de ignorarse silenciosamente.

Algunas particularidades de GHL que merece la pena conocer

• La versión de la API difiere por endpoint, no globalmente. GHL envía un encabezado de solicitud Version (2021-07-28 o 2021-04-15) que el servidor establece por llamada según lo que cada endpoint espera realmente; una versión incorrecta devuelve una forma de respuesta diferente silenciosamente, no un error, por lo que no hay un único valor predeterminado al que recurrir. 29 endpoints no envían ningún encabezado de versión; el servidor también lo iguala.

• Un PIT de ubicación no puede llamar a endpoints exclusivos de agencia, nunca, ningún ámbito lo soluciona. snapshots/*, saas-api/*, oauth/locationToken, oauth/installedLocations y la creación de objetos personalizados (POST /objects) requieren una credencial de nivel de agencia.

• 11 endpoints en la especificación oficial omiten la declaración de un parámetro de ruta (p. ej. un noteId en algunas rutas de calendario/conversación, un postId en blogs, un type en contactos). El generador los rellena como campos de cadena obligatorios, ya que el parámetro se usa claramente en la plantilla de ruta; esto es una brecha de la especificación ascendente, no algo introducido aquí.

• Los límites de velocidad aún no se han medido contra una cuenta real. El cliente reintenta en 429 usando el Retry-After que GHL envíe, pero no limita preventivamente con un número inventado; un límite asumido que sea incorrecto infrautilizaría la cuenta o empezaría a fallar llamadas que habrían tenido éxito.

Pruebas

npm test          # unit tests, mocked fetch
npm run smoke      # read only, against a live account

Desarrollo

La capa de herramientas se genera y no debe editarse a mano:

npm run gen-naming   # specification  ->  tool names
npm run gen-tools    # specification  ->  zod schemas and call sites
npm run build

Licencia

MIT, consulta LICENSE.

Creado por AIWerk. No afiliado con GoHighLevel / HighLevel Inc.