GoHighLevel prerequisites

Nội dung này hiện chưa có sẵn bằng ngôn ngữ của bạn.

GoHighLevel — also marketed as HighLevel, commonly abbreviated GHL — exposes its own MCP server at https://services.leadconnectorhq.com/mcp/. The Worker forwards 36 of GHL’s tools (contacts, calendars, conversations, opportunities, payments, social posts, blogs, email templates) verbatim to Claude. No tool re-implementation — just a thin proxy with auth, scope, audit logging, and a write-gate.

Naming note: code, DB, and admin UI use the canonical gohighlevel spelling. Tool descriptions surface “GoHighLevel / GHL / HighLevel” so Claude resolves either alias from user prompts.

1. Create a Private Integration Token (PIT) in HighLevel

Sign in to your HighLevel sub-account at app.gohighlevel.com.
Settings → Private Integrations → Create new token.
Tick the 32 scopes the MCP server actually uses:

View / Edit:
- Contacts, Conversations, Conversation Messages, Opportunities, Calendars, Calendar Events, Forms, Locations, Custom Fields, Payment Orders, Payment Transactions, Social Media Posts, Social Media Accounts, Email Templates
- Plus socialplannerstatisticsreadonly, blogslistreadonly, blogspostsreadonly, View Blog Authors, View Blog Categories, Update Blog Post, Check Blog Post Slug, Create Blog Post
Copy the token (starts with pit-). HighLevel only shows it once.

You’ll also need your sub-account / location ID. It’s visible in the URL of any HighLevel page (/v2/location/<id>/...) or under Settings → Company → Sub-account info.

2. Register the site

In /admin/sites (master login):

+ Add site
Display name: anything you’ll recognise (e.g. “Acme HighLevel”).
Platform: GoHighLevel (GHL / HighLevel CRM) — the form swaps to the GHL-specific fieldset.
Private Integration Token: paste the pit-... value.
Sub-account / location ID: paste the ID.
(Optional, super-admin) tick ⚠ Allow GoHighLevel write tools in Danger Zone if you want create/update/upsert/edit/add/remove/send tools to work. Leaving it off keeps the site read-only.
Save.

Behind the scenes the PIT is encrypted with the master token before it lands in D1. The dashboard never displays the ciphertext; it shows has_gohighlevel_pit: true instead.

3. Verify

Spin up Claude Desktop, point it at the worker, and ask:

List the MCP tools available for site <site_id>.

You should see 36 GHL tools (alongside any WP / Astro tools the token has scope for). Try a read tool first — it should respond without flipping the write flag.

Get contact <contactId> from <site_id>.

If that works, GHL is wired up. Write tools (e.g. contacts_create-contact, conversations_send-a-new-message) will return E_GOHIGHLEVEL_WRITE_NOT_ALLOWED until a super-admin ticks the flag.

Tool list — read vs write

Always available (24 tools)	Requires `allow_gohighlevel_write=1` (12 tools)
`calendars_get-calendar-events`	`contacts_add-tags`
`calendars_get-appointment-notes`	`contacts_remove-tags`
`contacts_get-all-tasks`	`contacts_update-contact`
`contacts_get-contact`	`contacts_upsert-contact`
`contacts_get-contacts`	`contacts_create-contact`
`conversations_search-conversation`	`conversations_send-a-new-message`
`conversations_get-messages`	`opportunities_update-opportunity`
`locations_get-location`	`social-media-posting_edit-post`
`locations_get-custom-fields`	`social-media-posting_create-post`
`opportunities_search-opportunity`	`blogs_create-blog-post`
`opportunities_get-pipelines`	`blogs_update-blog-post`
`opportunities_get-opportunity`	`emails_create-template`
`payments_get-order-by-id`
`payments_list-transactions`
`social-media-posting_get-post`
`social-media-posting_get-account`
`social-media-posting_get-social-media-statistics`
`social-media-posting_get-posts`
`blogs_check-url-slug-exists`
`blogs_get-blog-post`
`blogs_get-all-categories-by-location`
`blogs_get-all-blog-authors-by-location`
`blogs_get-blogs`
`emails_fetch-template`

The classifier (isGoHighLevelWriteTool in src/types.ts) decides write-vs-read by inspecting the action verb. Future GHL tools that follow the same naming convention pick up the right policy automatically.

Error reference

Code	Meaning
`E_GOHIGHLEVEL_WRITE_NOT_ALLOWED`	Tool mutates data but the site flag is off. Super-admin opt-in required.
`E_AUTH` (HTTP 401/403 upstream)	PIT is wrong, revoked, or missing a required scope. Recreate it in HighLevel.
`E_SITE_INVALID: gohighlevel_pit ... required`	Tried to create the site without supplying the PIT.
`E_NOT_SUPPORTED`	A tool wired to a non-GHL site (or a GHL tool called on a WP site). Pass the right `site_id`.

Cache + TTL

tools/list results from upstream GHL are cached per site for 1 hour in D1 (gohighlevel_tools_cache) plus 60s in the worker isolate. If you need to bust the cache early (e.g. after rotating the PIT or noticing new upstream tools), delete the site’s row from gohighlevel_tools_cache or call the upcoming reset_gohighlevel_cache admin endpoint.

Editing a site through /admin/sites does not auto-bust the cache; that’s intentional — the tool list rarely changes and the cost of a stale entry is bounded to the 1-hour TTL.