ghl-context-mcp

A deliberately small GoHighLevel MCP server. Six tools, scoped to one job: knowing who you're about to talk to.

Why this exists

The common failure mode when you put an agent on top of a CRM is a wide, generic tool surface that dumps raw API JSON: the model picks the wrong tool, burns its context window on fields no one would ever say out loud, and occasionally invents or overwrites a record. This server takes the opposite bet. It ships six tools, each scoped to the moment an agent is about to talk to a contact. Every field it returns is something a person would say or something the agent passes back on the next call. It does the date math itself, and it keeps writes off until you switch them on. The claim that a narrow surface beats a wide one is measurable, and the companion benchmark (mcp-tool-surface-bench) is being built to measure it.

The tools

Tool	What it does	Kind	Ceiling
find_contact	Resolve a name, phone, or email to exactly one contact, or return candidates	read	400
get_contact_timeline	Recent calls, SMS, notes, appointments, and stage changes as prose, with a headline	read	1200
get_pipeline_position	Where each deal sits, days in stage, value, and whether it stalled	read	500
get_appointments	Upcoming appointments for a contact or calendar, with relative times	read	900
log_note	Write a note, with retry-safe idempotency and an echo of what stored	write	200
move_stage	Move a deal to another stage, guarded by a stale-context check	write	250

Ceilings are per-response token budgets, enforced by a test that fails the build when a response grows past them. See DESIGN.md for what "token" means here.

Using it

This is an MCP server, and the intended user is an AI agent, not a person at a terminal. You connect the server to your agent (Claude Code, Claude Desktop, or any MCP-capable runtime), then talk to the agent in plain language. The agent is the one that decides to resolve a contact and pull their context.

Team quickstart with Claude Code

1. Clone the repo, then install and build:

   npm install && npm run build
   

2. Add your credentials:

   cp .env.example .env
   # then edit .env and fill in GHL_PIT and GHL_LOCATION_ID
   

3. Open the folder in Claude Code. It reads the checked-in .mcp.json, offers the ghl-context server, and you approve it once. The server loads .env on startup, so no token ever lives in a config file.

4. Talk to your agent the way a rep would at the start of the day:

   I'm calling Marcus Halloway and Priya Nair today. Give me a pre-call brief before each one.

   The agent resolves each contact, pulls the timeline, pipeline position, and upcoming appointments, and hands back the briefing.

Other MCP clients

Point any MCP client at the server over stdio. The published package needs no clone and no build. For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "ghl-context": {
      "command": "npx",
      "args": ["-y", "ghl-context-mcp"],
      "env": {
        "GHL_PIT": "pit-...",
        "GHL_LOCATION_ID": "your-sub-account-id"
      }
    }
  }
}

To run a local checkout instead of the published package, set command to node and args to your built dist/index.js.

Environment variables

Variable	Required	Default	Meaning
GHL_PIT	yes		Private Integration Token for one sub-account
GHL_LOCATION_ID	yes		The sub-account id the token belongs to
GHL_ALLOW_WRITES	no	false	Writes refuse unless this is exactly true
GHL_STALL_MULTIPLIER	no	2	Stall threshold as a multiple of median time-in-stage
GHL_RESOLVE_STRATEGY	no	fuzzy	fuzzy or exact contact retrieval

Create the token under Settings, Integrations, Private Integrations, with the scopes contacts.readonly, contacts.write, opportunities.readonly, opportunities.write, and calendars.readonly.

Seeing it without a client

If you do not have an MCP client handy, the repo ships a terminal demo that runs the same sequence an agent would and prints the brief:

npm run brief -- "Marcus Halloway"

It is a demonstration of the value, not the product. The product is the agent connection above.

From source

npm install
npm run build
npm test

npm test runs green with no credentials. The live checks, npm run live-check and npm run live-write-check, need a real .env.

Response shapes

A resolved contact:

{
  "resolution": "exact",
  "contact": {
    "contact_id": "NnAyKFnTSAVKg1amAArO",
    "name": "Marcus Halloway",
    "primary_phone": "+15551230010",
    "primary_email": "marcus.halloway@example.com",
    "tags": ["synthetic-seed"],
    "owner": null,
    "last_activity_at": null,
    "last_activity_summary": null
  }
}

An ambiguous match returns candidates instead of guessing:

{
  "resolution": "ambiguous",
  "candidates": [
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230012",
      "primary_email": "jordan.wells@example.com",
      "last_activity_at": null
    },
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230013",
      "primary_email": "jordan.wells.cpa@example.com",
      "last_activity_at": null
    }
  ],
  "disambiguate_by": ["email", "primary_phone"],
  "instruction": "Ask the user which one, or call again with the exact email or phone."
}

Ambiguity is treated as a success. An agent that hits an error stops, while one handed a candidate list keeps going and asks the user which contact they meant.

Errors

Every error is one shape. No raw HTTP status reaches the model.

Code	When	Retryable
CONTACT_NOT_FOUND	No contact matched the query	no
OPPORTUNITY_NOT_FOUND	No opportunity with that id	no
STAGE_NOT_IN_PIPELINE	Target stage is not in the pipeline (lists valid stages)	no
STALE_CONTEXT	The asserted current stage does not match live state	yes, after re-read
MISSING_CONFIRMATION	move_stage called without confirm	yes
WRITES_DISABLED	A write was attempted with writes off	no
SCOPE_MISSING	The token lacks a required scope	no
AUTH_INVALID	The token was rejected	no
RATE_LIMITED	GoHighLevel is throttling (carries retry_after_seconds)	yes
UPSTREAM_ERROR	GoHighLevel returned an error	yes, once
WINDOW_TOO_LARGE	The requested time window exceeds 365 days	yes

Design notes

The eight rules the server is built on, one line each. The long version, with the reasoning an interviewer would ask about, is in DESIGN.md.

1. One job per tool. If the description needs an "and", it is two tools.
2. Descriptions are written for the model: when to use, when not, and the sibling it's confused with.
3. No raw API shapes leave the boundary, enforced by a test.
4. Errors are instructions, in imperative voice, with valid options listed.
5. Every response has a token ceiling, enforced by a build-failing test.
6. The server does the arithmetic: ages, durations, relative times, counts.
7. Writes assert the state they depend on and fail loudly on a mismatch.
8. Writes are off unless GHL_ALLOW_WRITES=true.

What this does not do

Each cut is deliberate.

Not shipped	Why
create_contact, update_contact	Agents inventing or overwriting records is the top real-world failure. Creation belongs in a form or a human flow.
send_sms, send_email	Outbound messaging under agent control is a compliance surface. A context server has no business shipping it.
list_contacts, multi-filter search	Unbounded result sets burn a context window. The agent needs one resolved match, not a list.
list_pipelines, list_calendars	Schema-discovery tools mostly cost a turn. Names resolve to ids inside the tools, and invalid names return the valid options.
Workflow / automation triggers	Side effects the server cannot describe in advance or undo afterward.
get_precall_brief (a composite of the four reads)	Held back on purpose so the benchmark can test it as a separate arm. If it wins, it ships in v2 with the data behind it.

Limitations

Single location, Private Integration Token auth only, no OAuth. Pagination is bounded to the per-tool maximums. Stall detection needs volume to be meaningful and currently uses a fixed fallback because GoHighLevel exposes no stage history. Phone matching is US-centric. Token ceilings are proxy tokens, not exact Claude tokens. GoHighLevel reads trail writes by about a second. Tested against one account shape.

License

MIT