gohighlevel

What this skill does

# GoHighLevel (HighLevel / GHL)

## Overview

This skill provides a structured workflow for working with GoHighLevel through the **official HighLevel MCP server** at `https://services.leadconnectorhq.com/mcp/`. The server exposes ~36 tools today (calendars, contacts, conversations, opportunities, payments, social posting, blogs, email templates) and is on a roadmap to 250+.

## Prerequisites

1. **HighLevel MCP server connected** in `~/.claude/settings.json` under `mcpServers`.
2. **Private Integration Token (PIT)** generated from `Settings → Private Integrations` in the relevant Sub-Account, with the scopes the workflow needs.
3. **Location ID** (Sub-Account ID) for the account being acted on. Found in `Settings → Business Profile`, or in the URL after `/location/`.

If any tool call fails with an auth error, the PIT is wrong, expired, or missing scopes — re-issue it.

## Connection setup

Add this block under `mcpServers` in `~/.claude/settings.json`:

```json
"ghl": {
  "url": "https://services.leadconnectorhq.com/mcp/",
  "headers": {
    "Authorization": "Bearer pit-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "locationId": "YOUR_LOCATION_ID"
  }
}
```

After saving, restart Claude Code so the MCP server is picked up. Tools will appear as `mcp__ghl__*`.

### Required scopes (toggle in the PIT)

For full skill coverage enable: View/Edit Contacts, View/Edit Conversations, View Opportunities, View Calendars, View Payment Orders, View Custom Fields, View Social Media Posts/Accounts, View/Edit Email Templates, View/Edit Blogs.

Issue a narrower PIT if the agent only needs a subset.

## Required Workflow

**Follow these steps in order. Do not skip steps.**

### Step 1 — Confirm scope
Clarify the user's goal: which Sub-Account (Location), which object (contact / conversation / opportunity / calendar / payment / post / blog / template), and whether the action is read-only or a write. For writes, confirm the exact field values before calling the tool.

### Step 2 — Identify the right tool
Map the request to one of the tool families below. If the user references a record by name, do a search/list call first to resolve it to an ID, then pass the ID to the action call. Never fabricate IDs.

### Step 3 — Execute in batches
- **Read first** (search/list/get) to build context.
- **Write next** (create/update) with all required fields.
- For bulk operations, explain the grouping logic before applying changes and pause for confirmation if more than ~10 records will be modified.

### Step 4 — Summarize
Report what was read or changed, surface the GHL record IDs touched, and suggest the natural next step (e.g., "send a follow-up SMS to the 3 new leads", "add these contacts to a workflow").

## Available tool families

The MCP namespaces tools as `<resource>_<action>`. Common ones:

- **Calendars** — `calendars_get-calendar-events`, get/create appointments, list calendars
- **Contacts** — `contacts_get-contact`, `contacts_search-contact`, `contacts_create-contact`, `contacts_update-contact`, `contacts_add-tags`, `contacts_remove-tags`, `contacts_get-all-tasks`
- **Conversations** — `conversations_search-conversation`, `conversations_get-messages`, `conversations_send-a-new-message`
- **Opportunities** — `opportunities_search-opportunity`, `opportunities_get-pipelines`, `opportunities_get-opportunity`, `opportunities_update-opportunity`
- **Payments** — `payments_get-order-by-id`, `payments_list-transactions`
- **Custom Fields / Locations** — `locations_get-custom-fields`, `locations_get-location`
- **Social posting** — `social-media-posting_create-post`, list/get accounts and posts
- **Blogs** — `blogs_create-blog-post`, `blogs_get-blog-posts`
- **Email** — `emails_create-template`, list/get templates

Run a one-off `tools/list` (or just call any tool and read the error) to see the exact set available with the connected PIT — scopes change what surfaces.

## Practical workflows

- **Lead intake** — search contacts by phone/email, create if missing, add tags, then push into a pipeline opportunity.
- **Reply to a conversation** — search conversation by contact ID, get latest messages, send a new message (SMS / Email / GMB / FB / IG depending on channel).
- **Pipeline triage** — list pipelines → search opportunities in a stage → bulk move stale ones to a different stage with a comment.
- **Appointment lookup** — get calendar events for a date range, cross-reference contact records, surface no-shows.
- **Content publishing** — draft a blog post or social post, preview content, schedule via `create-post` / `create-blog-post`.
- **Revenue check** — list transactions or fetch an order by ID to confirm a payment before granting access.
- **Tag-based segmentation** — search contacts by tag, export to a list, hand off to an email/SMS workflow.

## Tips

- Always pass `locationId` explicitly in the tool args when the connected account is an Agency-level integration touching multiple Sub-Accounts. The header default only applies when not overridden.
- Phone numbers must be E.164 (`+15551234567`) for contact creation and SMS.
- Custom fields are referenced by ID, not name — fetch them once with `locations_get-custom-fields` and cache the mapping for the session.
- The MCP is rate-limited per Location; batch where possible and back off on 429.
- Writes are not transactional — if a multi-step workflow fails midway, report which IDs already changed so the user can decide whether to roll back manually.

## Troubleshooting

- **401 / 403** — PIT missing or lacks the required scope. Re-issue from `Settings → Private Integrations` with the right toggles.
- **`locationId` errors** — header is set but the PIT was issued in a different Sub-Account. PITs are scoped to the Location they were created in.
- **Tool not found** — the MCP only surfaces tools your scopes allow; add the scope, regenerate the PIT, restart Claude Code.
- **Stale data** — GHL eventually-consistent on some endpoints (especially conversations); re-fetch after a short delay rather than assuming a write didn't land.
- **Restart needed** — any change to `mcpServers` in `settings.json` requires a Claude Code restart to take effect.

## References

- Official docs: https://marketplace.gohighlevel.com/docs/other/mcp/index.html
- Support article: https://help.gohighlevel.com/support/solutions/articles/155000005741-how-to-use-the-highlevel-mcp-server
- Announcement: https://www.gohighlevel.com/post/introducing-the-mcp-server