GHL MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GHL MCP Server search GoHighLevel contacts for jane@example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AIGC: Label: "1" ContentProducer: 001191440300708461136T1XGW3 ProduceID: a60f8e46820ea466ef0868a20e79d739_64158b3be5e411f184bd52540072b1e8 ReservedCode1: ADkDg75IRrLxsmT7VnbMUurc8BBlgxLfJaAPJHOg7LWEW+ueKuioY8QFZATuWTNEoJRqsGNUWG3hepfwmbLmL0XuCNH64gdvihEnI1zsBxixRDIeuyfWuZ+sGc9Or4GFJdx0SR/5NygP6xaEPWOnfr1LmPFUBGE20oVc7hSW4hLlshTWaPLYF31SDDQ= ContentPropagator: 001191440300708461136T1XGW3 PropagateID: a60f8e46820ea466ef0868a20e79d739_64158b3be5e411f184bd52540072b1e8 ReservedCode2: ADkDg75IRrLxsmT7VnbMUurc8BBlgxLfJaAPJHOg7LWEW+ueKuioY8QFZATuWTNEoJRqsGNUWG3hepfwmbLmL0XuCNH64gdvihEnI1zsBxixRDIeuyfWuZ+sGc9Or4GFJdx0SR/5NygP6xaEPWOnfr1LmPFUBGE20oVc7hSW4hLlshTWaPLYF31SDDQ=
ghl-automation-engine
HighLevel (GoHighLevel) integration engine for teams that put automations in production and cannot afford them to be quietly wrong.
The GoHighLevel ecosystem already has a 900-tool MCP server. Tool count is not the bottleneck. Reliability is. This project is deliberately narrow: it makes the failure modes visible instead of silent.
Related MCP server: ghl-context-mcp
The four failures this exists to prevent
Failure | What it looks like in production | What this library does |
Silent pagination truncation | Page 2 of 5 fails, the caller returns page 1, a downstream workflow treats 100 contacts as "all contacts" and archives the rest | Cursor walking is exhaustive by contract: you get a |
Refresh-token stampede | 12 concurrent workers see an expired token, all refresh, the provider rotates the refresh token, 11 calls return | Single-flight refresh under a lock with a double-checked expiry, and the rotated token is persisted before the lock is released |
PII in logs | A debug line logs the contact upsert body and every email address lands in the log aggregator | Recursive redaction of credentials, emails, and phone numbers before any log record is emitted |
Untestable integrations | Every test needs a live sub-account and a private token, so there are no tests | An offline mock server with fault injection; the whole suite runs on a clean machine in seconds |
Webhook replays processed twice | A captured delivery is resent, or a platform retry arrives after a partial write, and the contact is created or the invoice is paid twice | Signature + timestamp window + an atomic seen-set; a duplicate returns |
Install
git clone <this repo>
cd ghl-automation-engine
python -m pytestNo dependencies. The runtime uses only the standard library, so pytest is the
only thing you need, and CI needs no Docker and no network.
Quickstart
from ghl_client import ContactsResource, GhlClient, PrivateIntegrationToken
client = GhlClient(
PrivateIntegrationToken(token="pit-..."),
location_id="loc_...",
)
contacts = ContactsResource(client)
result = contacts.search(query="@example.com")
if not result.complete:
raise SystemExit(f"refusing to act on {len(result)} of an unknown total")
for contact in result.items:
...Idempotent writes:
# Replaying this call does not create a duplicate contact.
contacts.upsert({"email": "jane@example.com"}, idempotency_key="sync-run-2026-11-21")Webhooks
from ghl_webhooks import Receiver
receiver = Receiver(["whsec_..."])
def handle_delivery(headers, raw_body):
intake = receiver.handle(headers, raw_body)
if intake.should_process:
dispatch(intake.event) # a real, first-time, verified event
return intake.http_status, {"status": intake.status.value}Three things this does that a naive handler does not:
Order matters. Nothing is parsed until the signature verifies, and no event id is claimed until every other check has passed — so an attacker cannot burn event ids to block genuine deliveries.
Duplicates are visible. A repeat delivery answers
200withprocess=false. The sender stops retrying; your application does not re-run. "Received" and "acted on" are different questions and both get an answer.Unknown event types are kept. An unrecognised type is delivered with
event.is_known == Falseand its raw body intact. Silently discarding it is how an integration appears healthy while ingesting nothing.
Signature framing (header names, hex vs base64, what exactly is signed) is configuration
rather than a guess, because getting it wrong silently rejects real traffic. See
docs/adr/ADR-002-webhook-signature-framing.md for the default assumption and how to
confirm it against one captured delivery.
Run the intake demo — no network, no credentials:
python examples/demo_webhooks.pyGoverned MCP server
export GHL_PIT_TOKEN=pit-... export GHL_LOCATION_ID=loc_...
export GHL_MCP_MODE=read-write # default is read-only
export GHL_MCP_APPROVAL_SECRET=... # required before any write will run
ghl-mcp # JSON-RPC over stdioFive tools: get_contact, search_contacts, upsert_contact, rate_limit_status,
server_governance. Scope is narrow on purpose — a tool that returns a plausible empty
result is worse than a tool that is absent, so the unimplemented ones are listed with
reasons instead of being faked.
The part that matters is the interceptor every call passes through, in this order:
Mode. Read-only unless the operator turned writes on. A refusal is
read_only_mode, never a200with an empty body.Schema. Unknown properties are rejected, so there is no
locationIdto argue about — cross-account access is not a policy, it is a shape that does not exist.Location. The server is bound to one sub-account; an unbound client gets
cross_locationrather than a default location.Approval. A write needs a single-use, short-lived token issued for that tool and those exact arguments. A token for one contact cannot be spent on another.
Budget. Session ceilings stop a loop before the platform rate limiter or the invoice does.
# the human approves one specific change
ghl-mcp approve --tool upsert_contact \
--args '{"email":"ada@example.com","first_name":"Ada"}'upsert_contact also takes dry_run: true, which returns the payload it would send and
touches nothing. server_governance reports the active policy, the PII allowlist, and the
blocked-tool list. Without GHL_PIT_TOKEN the server exits 2 and says why, instead of
starting up to answer 401s that an agent would narrate as "no contacts found".
Full detail: docs/MCP.md.
Offline development
python -m ghl_mock --port 8080
python examples/demo_offline.py # full round trip against the mockThe mock can be told to fail on purpose, which is the point:
curl -X POST localhost:8080/__admin/inject \
-H 'content-type: application/json' \
-d '{"path": "/contacts/search", "status": 429, "times": 1, "retry_after": "2"}'Architecture
src/ghl_client/
errors.py typed hierarchy; retryable is a property of the error, not the caller
ratelimit.py sliding-window budget, 90 req / 10 s (platform allows 100)
retry.py Retry-After (seconds and HTTP-date), capped at 120 s, full jitter
transport.py the only module that touches a socket; injectable
auth.py private tokens + OAuth with single-flight refresh and persistence
pagination.py exhaustive cursor walking with loop detection
client.py versioning, budgeting, redaction, request ids
resources/ contacts (search, idempotent upsert)
src/ghl_mock/
store.py in-memory contacts with email/phone dedupe and cursor paging
app.py stdlib HTTP server + fault injection admin endpoints
src/ghl_mcp/
server.py JSON-RPC over stdio; call_tool is the only path to a handler
governance.py mode, approval tokens bound to arguments, session budget, location guard
tools.py five tools, each declaring scope, risk, endpoint and dry-run support
registry.py tool specs; carries requires_location per tool
schema.py strict JSON Schema subset: unknown keywords raise instead of being ignored
projection.py PII allowlist and field truncation for anything a model will read
audit.py one JSON line per call: digests, decision, duration — never the arguments
src/ghl_webhooks/
signature.py HMAC verification; header/encoding/prefix/signed-payload are configuration
replay.py timestamp window + atomic seen-set behind a one-method store protocol
events.py event parsing that preserves unknown types instead of dropping them
receiver.py ordered intake: size -> signature -> timestamp -> parse -> claim
src/ghl_attribution/
mapping.py required field keys, live id binding, drift as a startup error
events.py webhook body -> touch; "no campaign signal" is a first-class answer
policy.py which fields may be written: blanks + activity time, credit preserved
ledger.py event claim store (in-process default, protocol for a durable one)
engine.py discovery -> claim -> compare -> upsert; dry run returns the deltaDesign decisions worth defending:
Mock before client. The contract is written down as executable mock behaviour first, so the client is developed against a specification rather than against whatever the live API happened to return at 3 a.m.
Errors carry context. Status, method, path, request id, and location id are attached at the point of failure, so a support ticket does not need a repro.
No dependency on the platform's SDK. The SDK pulls its own HTTP stack and its own opinions about retries; both would fight with the retry and budget logic above.
A dropped connection is a dataset, not a surprise.
urllibwraps neitherECONNRESETnor Windows'WSAECONNABORTED, so the transport types them itself: every socket-level failure becomes a retryableGhlTransportErrorinstead of a bareOSErrorthat a calling workflow has no reason to handle.
Attribution engine
The server is only half of it: leads arrive from forms, quizzes, and landing
pages, and the reason to send them to GoHighLevel is attribution. ghl_attribution
does that without the two failure modes that make attribution worthless — a lead
re-credited on every later visit, and one lead in the CRM three times over.
from ghl_attribution import AttributionEngine
engine = AttributionEngine(client) # resolves custom field ids at startup
result = engine.ingest({ # webhook body, verbatim
"event_id": "evt-9f2",
"email": "lead@example.com",
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "spring",
"occurred_at": "2026-11-20T10:00:00Z",
})
result.status # IngestStatus.APPLIED
result.applied # ("utm_source", "utm_medium", "utm_campaign", "first_touch_at", "last_touch_at")Credit is append-only. A later touch from another source advances
last_touch_atand nothing else.utm_source=directfrom a returning lead cannot erase the campaign that paid for them.Two idempotency layers. The event claim stops a redelivered webhook, the client's upsert ledger stops a duplicate contact after a failed retry, and the claim is released on failure so a retry is the same operation.
Refuses to start on schema drift. Missing, retyped, or duplicated custom fields raise
AttributionMappingErrorwith every problem listed — before the first write, not after the reports break.dry_run=Truereturns the exact field payload without writing.
Full detail, including the required field keys: docs/ATTRIBUTION.md.
A worked case runs offline — seven relay deliveries (two of them redeliveries), a later touch, a direct revisit, a dry run, and a mid-flight schema drift:
python examples/case_lead_attribution.pyIt ends with two contacts, the paid-search credit intact, and the drift refused
before the first write. Write-up: docs/CASE-STUDY-ATTRIBUTION.md
— figures that need a real deployment are marked TBD, not guessed.
Status
Built and tested:
typed errors, sliding-window rate budget, retry with
Retry-AfterOAuth single-flight refresh with file persistence
exhaustive cursor pagination with partial-result signalling
contacts search and idempotent upsert
offline mock server with fault injection (429 / 5xx / auth rejection)
webhook intake: HMAC verification, timestamp window, replay seen-set, unknown-type preservation
governed MCP server: read-only default, argument-bound single-use approvals,
dry_run, location guard, session budget, digest-only audit log, blocked tools declared not fakedattribution engine: append-only first-touch credit, event claim + upsert ledger, custom-field discovery with drift refusal, dry-run plans
attribution case study: reproducible demo + page, invariants pinned by tests
198 tests, no network, no credentials
Not built yet, on purpose — in this order:
live smoke tests behind an opt-in environment flag
durable replay store adapter (Redis/Postgres) beyond the in-process default
multi-touch weighting (first touch is the only model implemented today)
License
MIT. See LICENSE. (内容由AI生成,仅供参考)
Available Tools
5 toolsget_contactARead-onlyIdempotent
Fetch one contact by id. Returns allowlisted fields only.
Inputs: contact_id (required).
rate_limit_statusARead-onlyIdempotent
Remaining request budget in the client's local sliding window. No network call.
Inputs: no named parameters.
search_contactsARead-onlyIdempotent
Search contacts in the bound sub-account. Paginates every cursor and reports complete=false when a limit stopped the walk. Returns allowlisted fields only.
Inputs: limit, query.
server_governanceARead-onlyIdempotent
This server's own policy: mode, approval requirement, PII allowlist, and the tools that are deliberately not implemented.
Inputs: no named parameters.
upsert_contactAIdempotent
Create or update a contact, deduplicated on email/phone. Idempotent on replay. Pass dry_run=true to preview the change without writing.
Inputs: tags, email, phone, dry_run, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The three contact tools (search_contacts, get_contact, upsert_contact) have crisp, non-overlapping boundaries. The two meta tools, server_governance and rate_limit_status, are both 'server self-info' and could be momentarily confused, but their descriptions clearly separate policy from budget.
All names use snake_case, and the contact tools follow a clean verb_noun pattern (search/get/upsert_contact). server_governance and rate_limit_status break the verb_noun pattern as noun phrases, a minor deviation that is still readable.
Five tools is well within a sensible scope for a narrowly bound contact sub-account server. Two of the five are diagnostic/meta rather than domain operations, making the functional surface slightly thin.
Create/update, single fetch, and search are covered, but there is no delete/archive operation and no way to list or filter beyond cursor pagination (e.g. by tag or owner). Agents will hit a dead end if a contact must be removed or bulk-managed.
Maintenance
Related MCP Connectors
Project-scoped marketing ops for agents: Bearer dpk_/dpa_ or OAuth, read and supervised write.
Read and write a CRM built for agents. Every change carries who asserted it and how.
Agent-native CRM. 25 tools — contacts, deals, sequences, enrichment waterfall, audit log.
Governance runtime for compliance: verified, human-approved writes to a tamper-evident record.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI agents to safely operate HubSpot CRM contacts, deals, and pipelines via MCP, with caching, idempotency, audit trails, and robust error handling.15MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to pull focused GoHighLevel context before talking to a contact, including contact lookup, timeline summaries, pipeline positions, and appointments, with optional guarded writes. It helps agents brief themselves on a person without exposing raw CRM API noise.6 npmMIT
- FlicenseBqualityCmaintenanceEnables AI assistants to operate GoHighLevel agencies through the official v2 API, managing contacts, deals, conversations, appointments, tags, custom fields, workflows, and pipeline reports with bulk operations and fail-closed security.12-
- AlicenseAqualityBmaintenanceEnables governed access to a canonical Customer Graph across CRM and customer-service records, with per-field provenance, propose-only identity merges, field-level masking, records-only reply drafting, tiered policy and kill-switch enforcement, and hash-chained receipts for auditable reads and internal writes.9MIT