GoHighLevel MCP Server

Ein Model Context Protocol-Server, der einem LLM-Agenten operative Kontrolle über eine GoHighLevel-CRM gibt – 114 Tools in 24 Modulen, die Kontakte, Pipelines, Kalender, Messaging, Rechnungsstellung und Zahlungen über die GoHighLevel-API v2 abdecken.

Das Problem

GoHighLevel ist das System of Record für eine kleine Agentur: jeder Kunde, jede Buchung, jede Rechnung. Die Arbeit, die den Tag wirklich auffrisst, ist keine einzelne CRM-Aktion, sondern das Verknüpfen zwischen ihnen – ein Shooting wird bestätigt, also muss jemand die Opportunity anlegen, sie in die richtige Pipeline-Phase verschieben, den Kalenderslot für den richtigen Kontakt buchen, die Rechnung entwerfen und eine Notiz verfassen. Jede Schritt für sich ist ein dreißig Sekunden langes Klicken, und die Sequenz läuft mehrere Male pro Woche.

Genau diese Sequenz kann ein Agent ausführen, wenn er auf das CRM zugreifen kann. Dieser Server ist genau dieser Zugriff: Er macht GoHighLevel als typisierte, mit Annotationen versehene Tools verfügbar, sodass ein Agent die gesamte Kette aus einem einzigen Anweisungssatz heraus ausführen kann, während die destruktiven und nach außen gerichteten Schritte für die Bestätigung sichtbar bleiben.

Related MCP server: GoHighLevel MCP Server

Architektur

24 Tool-Module registrieren sich über stdio bei einem McpServer. Der gesamte Datenverkehr läuft über eine einzige ghlRequest()-Funktion, die Authentifizierung, den obligatorischen Version-Header, die Query-String-Assemblierung und das Formen von Fehlern übernimmt. Module lassen sich beim Start über GHL_DISABLED_MODULES ein- und ausschalten – das ist wichtiger, als es klingen mag, denn 114 Tool-Definitionen bedeuten einen erheblichen Teil des Kontextfensters eines Agenten, bevor auch nur ein einziges Wort der Benutzeranfrage gelesen wurde. Ein Deployment, das nur Buchungen verarbeitet, kann sechs Module registrieren und den Rest überspringen.

  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

Jedes Schreib-Tool trägt MCP-Annotationen – 17 sind als destructiveHint markiert, und ghl_send_message / ghl_send_invoice sind als nach außen gerichtet gekennzeichnet, weil sie echte Kunden erreichen. Der Host zeigt diese Markierungen an, bevor er einen Aufruf genehmigt – das ist der Unterschied zwischen einem Agenten, der eine Rechnung entwirft, und einem Agenten, der versehentlich eine an einen Kunden schickt.

Der wirklich harte Teil

Eine Rechnung zu erstellen. Der Endpunkt erwartet businessDetails- und contactDetails-Blöcke, und die Dokumentation untertreibt beides: Wenn man versucht, eine contactId und ein paar Positionen wie in der Dokumentation beschrieben zu übermitteln, kommt der Fehler zurück, der kein Feld benennt. Beide Blöcke müssen vollständig angegeben werden, und businessDetails.phoneNo und contactDetails.phoneNo sind Pflichtfelder – ein Kontakt mit E-Mail-Adresse und ohne Telefonnummer kann überhaupt nicht in Rechnung gestellt werden.

Noch schlimmer ist, dass die Werte mit dem übereinstimmen müssen, was die UI erzeugt, sonst sehen per API erstellte Rechnungen anders aus als handgefertigte Rechnungen – anderes Logo, fehlende Konditionen, falsche Nummerierung. Diese Standardwerte stehen nicht in dem Standortprofil, wo man sie erwartet; sie liegen hinter GET /invoices/settings, also derselben Quelle, aus der auch die UI ihre Vorbelegung nimmt.

src/tools/billing-helpers.ts löst beide Blöcke auf, sodass die Tools nur eine contactId benötigen. Für Geschäftsdaten durchlaufen vier Ebenen: Argument beim Aufruf, GHL_BUSINESS_*-Umgebungsvariable, gespeicherte Rechnungseinstellung, Standortprofil – jede Ebene füllt nur das auf, was die darüber liegende leer ließ. Kontaktdienste werden abgerufen und zusammengesetzt; für name gibt es die Rückfallebenen vollständiger Name, Vor– und Nachname, Name des Unternehmens, E-Mail und zuletzt Telefon, weil GoHighLevel leere Namen ablehnt und echte CRM-Angaben häufig keinen Namen haben. Beide Pfade werfen eine Meldung, die das fehlende Feld und die Möglichkeit benennt, es bereitzustellen, statt GHLs undurchschautes 422 an die Oberfläche zu bringen. Jede Abfrage wird pro Standort zwischengespeichert, sodass ein Stapel aus zehn Rechnungen einen Abruf der Einstellungen kostet, nicht zehn.

Was ich anders machen würde

1. Keine Tests. 4.000 Zeilen und keine. Die Fallback-Kette in billing-helpers ist pure Logik über Fixture-Daten – die einfachste Sache im Repository, um sie gegen Dinge, und gleichzeitig die teuerste Fehlerquelle, denn Fehlerformat ist eine falsch formatierte Rechnung, die an eine Kund spurllt.

2. Kein Retry bei 429. ghlRequest teilt dem Aufrufer mit, dass „rate limited; retry in nach kurzer Verzögerung“ vor, und dann wird nicht erneut versucht. Backoff gehört in den Client und nicht in das Urteilsvermögen des Agenten.

3. Die Caches sind Modul-Level-Maps mit ohne LeitungsInvalidierung. Für einen stdio-Server, den der Host normalerweise beim Start einfach neu startet, ist das richtig; falsch wird es, sobald dieser Prozess über einen längeren Zeitraum läuft und eine Änderung des Business-Profi none get wird.

4. Antworten sind durchgängig Record<string, unknown>. GoHighLevel stellt eine OpenAPI-Spezifikation bereit; würd gewinnen, würde es eine Klasse von Laufwert-Begehen er Zeit in Compile-Fehler er verwandeln.

5. 114 Tools in einem Server sind zu viele. Modul-Toggles sind ein Workaround, keine Lösung. Es ist besser, eine kleine Gruppe von Tools und einen Mechanismum für die Entdeckung zu haben, damit der Agent nur zahlt, was er auch nutzt.

Einrichtung

Sie benötigen Node.js 20+ sowie ein GoHighLevel-Konto.

1. Ein Private-Integration-Token erstellen

Einstellungen → Private Integrationen → Neue Integration erstellen. Aktivieren Sie die Bereiche, die zu den Projektionswerkzeugen passen, die Sie verwenden möchten; mindestens:

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

Kopieren Sie das Token – es beginnt mit pit-.

2. Finden Sie Ihre Standort-ID

Einstellungen → Unternehmensprofil, oder lesen Sie diese direkt aus der Dashboard-URL ab: .../location/<LOCATION_ID>/...

3. Erstellen

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

4. An einem MCP-Host registrieren

{
  "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"
      }
    }
  }
}

Starten Sie den Host neu. Eine Liste aller unterstützten Variablen finden Sie in .env.example, einschließlich des Rechnungs-Business-Blocks und der Modul-Schalter.

Um den Server ohne Host zu testen:

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

Ein Hinweis zum Thema „Automationen erstellen“

Die GoHighLevel-API kann keine Workflow-Logik erstellen – das visuelle Konstrukt ist rein für die Benutzeroberfläche. Das unterstützte Muster ist: einen Workflow einmalig in der UI zu erstellen, seine ID mit ghl_list_workflows zu ermitteln und Kontakte mit ghl_add_contact_to_workflow einzuschreiben.

Tool-Referenz

Lizenz

MIT – siehe LICENSE. Nicht verbunden mit oder unterstützt von GoHighLevel.