ghl-mcp-server CLAUDE.md

CLAUDE.md

Project context for Claude Code, Cursor, and other AI coding tools working on this repository. For end-user install instructions, see README.md. For machine-readable server discovery, see mcp.json.

---

What This Is

GHL MCP Server is a Model Context Protocol (MCP) server that exposes the GoHighLevel CRM API as tools an AI agent can call. It ships 60+ tools covering contacts, conversations, calendars, pipelines, payments, invoices, workflows, and more.

• Built by: Saurabh K Shah (https://saurabhshah.com)
• License: MIT
• Language: TypeScript (Node.js, ESM)
• MCP SDK: @modelcontextprotocol/sdk
• Transports: stdio (for Claude Desktop / Claude Code) and HTTP Streamable (for N8N and remote clients)

---

Repository Layout

ghl-mcp-server/
├── src/
│   ├── index.ts                # Entry point, transport selection, server wiring
│   ├── constants.ts            # GHL API endpoints, rate limits, version headers
│   ├── types.ts                # Shared TypeScript interfaces
│   ├── services/
│   │   └── api-client.ts       # HTTP client: auth, rate limiting, error mapping
│   └── tools/
│       ├── contacts.ts         # Contact CRUD, tags, notes, tasks, workflow attach
│       ├── conversations.ts    # SMS/Email/WhatsApp messaging, threads
│       ├── calendars.ts        # Calendars, free slots, appointments
│       ├── opportunities.ts    # Deals, pipelines, stage transitions
│       └── business.ts         # Payments, invoices, workflows, forms, social, misc
├── dist/                       # Compiled JS output (committed? check .gitignore)
├── mcp.json                    # Machine-readable server manifest
├── CLAUDE.md                   # This file
├── README.md                   # End-user docs
├── package.json
├── tsconfig.json
└── .env.example

---

How It Works

1. src/index.ts creates a single McpServer instance.
2. Each file in src/tools/ exports a register*Tools(server) function that calls server.tool(name, schema, handler) for each tool it owns.
3. All tool handlers go through src/services/api-client.ts, which handles auth headers, the GHL Version header, rate limiting (100 req / 10s burst, 200k/day), and error mapping.
4. Transport is chosen at startup via the TRANSPORT env var: stdio (default) or http.