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.

Related MCP server: GHL MCP Server

The tools

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

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.

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.

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