@aiwerk/mcp-server-ghl

MCP-Server für die GoHighLevel (GHL)-API, die CRM- und Marketing-Automatisierungsplattform, die von Agenturen genutzt wird, um die Vertriebspipelines, Kalender, Konversationen und Kampagnen ihrer Kunden zu verwalten.

569 Tools in 41 Domänen, generiert aus GHLs offizieller OpenAPI-3.0.0-Spezifikation.

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

Warum generiert

Jeder Endpunkt, jedes HTTP-Verb, jeder Parameter- und Feldname stammt aus der offiziellen Spezifikation und nicht aus Prosa-Dokumentation, sodass die Tool-Oberfläche nicht von dem abweichen kann, was GHL tatsächlich akzeptiert. Was die Spezifikation nicht verraten kann – welche Endpunkte ein Token auf Agenturebene statt eines Standort-Tokens benötigen, welche API-Version ein Endpunkt erwartet, welche Felder die Dokumentation vergessen hat als erforderlich zu markieren – wird von Hand darübergelegt. Siehe GHL-Besonderheiten, die es wert sind, zu wissen.

Related MCP server: GoHighLevel MCP Server

Installation

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

Erfordert Node.js 18 oder neuer.

Authentifizierung

Erstellen Sie ein Private Integration Token (PIT) für den Zielstandort unter Einstellungen > Private Integrationen. Ein PIT ist auf einen Standort beschränkt, es ist keine bereichsweite Anmeldeinformation, und die meisten Tools müssen wissen, auf welchen Standort sie sich beziehen.

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

Verwendung

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

AIWerk-gehosteter Dienst

Installieren Sie es aus dem Katalog auf aiwerkmcp.com und fügen Sie Ihr Token in der Oberfläche hinzu. Keine lokale Einrichtung erforderlich.

Sicherheitsfunktionen

Trockenlauf

export GHL_DRY_RUN=1

Jeder Schreibvorgang (POST/PUT/PATCH/DELETE) wird gestoppt, bevor er GHL erreicht, und gibt eine Beschreibung der Anfrage zurück, die gesendet worden wäre. Lesevorgänge funktionieren weiterhin normal.

Nur-Agentur-Endpunkte geben einen klaren Fehler zurück, kein nacktes 401

39 Endpunkte (Snapshots, die SaaS-API, Agency-OAuth-Token-Austausch, Erstellen benutzerdefinierter Objekte) erfordern ein Token auf Agenturebene. Ein Standort-PIT erhält von GHL für diese eine einfache 401-Antwort ohne Erklärung im Body. Der Server weiß, um welche Endpunkte es sich handelt, und gibt eine entsprechende Meldung zurück, anstatt es wie ein falsches oder abgelaufenes Token aussehen zu lassen.

locationId wird automatisch ausgefüllt

Ein PIT ist bereits auf einen Standort beschränkt, daher akzeptieren 430 der 569 Tools locationId (oder altId/altType) als optionalen Parameter. Wenn der aufrufende Agent keinen angibt, greift der Server auf GHL_LOCATION_ID zurück. Das bedeutet auch, dass ein Tool-Aufruf nicht versehentlich den falschen Standort ansteuern kann, indem eine kopierte ID aus einem anderen Konto verwendet wird, da der Standardwert immer dem eigenen Geltungsbereich des Tokens entspricht.

Konfiguration

Verkleinern des Tool-Satzes

Alle 569 Tools sind standardmäßig registriert. Ein Client, der eine kleinere Oberfläche bevorzugt, kann den Server auf bestimmte Domänen beschränken (Domänennamen sind mit Bindestrich geschrieben, z. B. social-media-posting, ad-manager):

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

Unbekannte Domänennamen werden beim Start gemeldet, anstatt stillschweigend ignoriert zu werden.

Einige GHL-Besonderheiten, die es wert sind, zu wissen

• Die API-Version unterscheidet sich pro Endpunkt, nicht global. GHL sendet einen Version-Anfrageheader (2021-07-28 oder 2021-04-15), den der Server pro Aufruf basierend auf den tatsächlichen Erwartungen des jeweiligen Endpunkts setzt. Eine falsche Version gibt stillschweigend eine andere Antwortstruktur zurück, keinen Fehler, daher gibt es keinen einzelnen Standard, auf den man zurückfallen kann. 29 Endpunkte senden überhaupt keinen Versionsheader; der Server gleicht auch das ab.

• Ein Standort-PIT kann niemals Agentur-Endpunkte aufrufen, kein Geltungsbereich behebt das. snapshots/*, saas-api/*, oauth/locationToken, oauth/installedLocations und das Erstellen benutzerdefinierter Objekte (POST /objects) erfordern eine Anmeldeinformation auf Agenturebene.

• 11 Endpunkte in der offiziellen Spezifikation lassen die Deklaration eines Pfadparameters aus (z. B. eine noteId bei einigen Kalender-/Konversationsrouten, eine postId bei Blogs, ein type bei Kontakten). Der Generator füllt diese als erforderliche Zeichenfolgenfelder aus, da der Parameter offensichtlich in der Pfadvorlage verwendet wird. Dies ist eine Lücke in der Upstream-Spezifikation, nicht etwas, das hier eingeführt wurde.

• Rate Limits wurden noch nicht gegen ein Live-Konto gemessen. Der Client wiederholt bei 429 mit dem Retry-After-Wert, den GHL sendet, drosselt aber nicht vorbeugend mit einer erfundenen Zahl. Eine angenommene Grenze, die falsch ist, würde entweder das Konto unterauslasten oder Aufrufe fehlschlagen lassen, die erfolgreich gewesen wären.

Testen

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

Entwicklung

Die Tool-Schicht wird generiert und darf nicht von Hand bearbeitet werden:

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

Lizenz

MIT, siehe LICENSE.

Erstellt von AIWerk. Nicht verbunden mit GoHighLevel / HighLevel Inc.