ghl-mcp: Instructions file for Claude Code

GoHighLevel MCP Server

What You're Building

An MCP (Model Context Protocol) server that wraps the GoHighLevel (GHL) API v2, exposing GHL operations as MCP tools. This lets any MCP-compatible AI agent (Claude Code, Cursor, Codex, OpenClaw, VS Code) interact with GoHighLevel CRM data.

Think of it as: The HubSpot MCP server, but for GoHighLevel.

Tech Stack

• TypeScript (strict mode)
• @modelcontextprotocol/sdk v1.x (stable — NOT v2 which is pre-alpha)
• zod for input validation
• node-fetch or built-in fetch for API calls
• stdio transport (standard MCP pattern for CLI usage)

Package Info

• Name: @snackjpg/ghl-mcp
• Binary: ghl-mcp
• Entry: src/index.ts
• Build: TypeScript → dist/
• License: MIT

GoHighLevel API v2 Reference

Base URL: https://services.leadconnectorhq.com

Auth: Bearer token in Authorization header

Authorization: Bearer {GHL_API_TOKEN}
Content-Type: application/json
Version: 2021-07-28

The token comes from either:

1. A Private Integration token (simpler, for single-location)
2. OAuth 2.0 access token (for marketplace apps, multi-location)

For this MCP server, support both via environment variables:

• GHL_API_TOKEN — Bearer token (private integration or OAuth access token)
• GHL_LOCATION_ID — Location/sub-account ID (required for most endpoints)

API Endpoints to Implement

Contacts (Priority: HIGH)

• GET /contacts/{contactId} — Get contact by ID
• GET /contacts/ — List/search contacts (query params: query, locationId, limit, offset)
• POST /contacts/ — Create contact
• PUT /contacts/{contactId} — Update contact
• DELETE /contacts/{contactId} — Delete contact
• POST /contacts/search — Search contacts (advanced, with filters)
• GET /contacts/{contactId}/tasks — Get contact's tasks
• POST /contacts/{contactId}/tags — Add tags to contact
• DELETE /contacts/{contactId}/tags — Remove tags from contact
• GET /contacts/{contactId}/notes — Get contact notes
• POST /contacts/{contactId}/notes — Create note on contact