# BackCrew GoHighLevel MCP Server

Think of this like a brand-new employee on their first day, not a business partner. A new hire only does the exact tasks you've shown them, nothing more, until you decide they're ready for more responsibility.

It lets you connect an AI assistant like Claude or ChatGPT to your [GoHighLevel](https://www.gohighlevel.com/) (HighLevel) account, so you can ask for things in plain English, like "find this lead," "what's in our pipeline," "text this customer back," instead of clicking through GoHighLevel yourself. On day one, it only knows how to look things up. You decide if and when to train it up to doing more.

GoHighLevel is a lead-gen and marketing CRM heavily used by agencies that run marketing for service businesses, including pest control companies whose marketing is managed through it. This repo is built to run **alongside** one of BackCrew's FSM servers in the same AI assistant, so a missed-call or new-lead workflow can span both lead capture and job scheduling.

Built by **[BackCrew](#built-by-backcrew)**, part of a series of free tools like this for pest control businesses.

> Not a developer? That's fine. Everything up through "Testing it safely" is written for you, no coding background needed.

---

## Contents

- [What this actually does](#what-this-actually-does)
- [Why use an independent MCP server instead of the platform's own AI?](#why-use-an-independent-mcp-server-instead-of-the-platforms-own-ai)
- [Scope: this is intentionally narrow](#scope-this-is-intentionally-narrow)
- [Also from BackCrew](#also-from-backcrew)
- [Some words you'll see, explained](#some-words-youll-see-explained)
- [How this keeps you safe by default](#how-this-keeps-you-safe-by-default)
- [What it can look up (always safe)](#what-it-can-look-up-always-safe)
- [⚠️ What it can change (off by default)](#what-it-can-change-off-by-default)
- [How to set it up](#how-to-set-it-up)
- [Connecting it to Claude](#connecting-it-to-claude)
- [Testing it safely](#testing-it-safely)
- [For developers](#for-developers)
- [What's next](#whats-next)
- [Built by BackCrew](#built-by-backcrew)
- [License](#license)

## What this actually does

Let's be upfront about what this is, because it's easy to oversell: this is **not** an all-knowing marketing assistant that understands your leads and handles things for you. It's a specific, listed set of actions that an AI assistant is allowed to trigger when you ask for them in plain English. The AI doesn't have judgment about your business; it matches what you ask for to the closest action on its list and does exactly that, nothing more.

## Why use an independent MCP server instead of the platform's own AI?

Software platforms are increasingly shipping their own built-in AI features. Worth knowing why you might still reach for this instead:

- **No plan-tier gates.** Native AI features are often locked to a platform's most expensive plan. This project just needs API access, which is usually available on lower tiers too.
- **Cross-platform, not walled off.** A platform's own AI only sees that platform's own data. It has no reason to work fluently with your FSM software, your accounting software, or your email, since those are somebody else's product. An MCP-connected assistant can have multiple servers attached at once (this one plus one of BackCrew's FSM servers), so it can work across your whole stack in one conversation.
- **Your choice of AI, not theirs.** You keep using whichever assistant you already trust (Claude, ChatGPT, whatever) instead of learning a new vendor-specific AI interface.

## Scope: this is intentionally narrow

GoHighLevel's platform is huge (funnels, websites, workflows, memberships, reputation management, and more). This repo covers exactly what's relevant to a pest control business handling leads:

- **Contacts**: the people (leads, prospects, customers)
- **Opportunities**: sales pipeline entries tied to a contact
- **Conversations**: SMS/email/call threads with a contact, and sending new messages
- **Calendar**: checking availability and booking/managing appointments

Not covered: funnels, websites, workflows (triggering them), memberships, reputation/review management, payments, and most of the rest of the platform. See [ROADMAP.md](ROADMAP.md).

## Also from BackCrew

This is one of several MCP connectors BackCrew builds, same idea, different software. We've also got FSM connectors like Housecall Pro, plus QuickBooks for the accounting side. Full list and what's live right now: see [ROADMAP.md](ROADMAP.md).

**Beyond this repo:** once a business gets comfortable with an AI assistant reading its data, there's often more it wants to do with it, like catching missed calls faster, processing invoices and paperwork automatically, following up on quotes without someone having to remember, reactivating customers who've gone quiet, or pulling reports without digging through the software. That's a separate, scoped conversation, not part of this free, open-source repo. Same contact as in [Built by BackCrew](#built-by-backcrew) below if it's something you want to explore.

## Some words you'll see, explained

- **API**: a locked door into GoHighLevel's data that only software can open. This project is a key that opens that door.
- **MCP**: the standard way an AI assistant like Claude or ChatGPT is told what it's allowed to do.
- **Server**: a small program that sits between your AI assistant and GoHighLevel, translating requests back and forth.
- **Location**: GoHighLevel's term for a specific sub-account (one business). This server is configured to operate on exactly one Location.
- **Private Integration Token**: GoHighLevel's self-service equivalent of an API key, scoped to one Location. No separate developer account or OAuth flow needed for connecting to your own account.
- **Terminal**: a plain-text window where you type commands.
- **Tool**: one specific, individually named action the AI is allowed to take.

## How this keeps you safe by default

- **Out of the box, this server can only look things up.** It ships in **read-only mode**.
- **When you're ready for more, you choose a responsibility level:**
  - `readonly-owner`: same as the default. Look-ups only.
  - `office-ops`: create/update contacts and opportunities, send messages, book/update appointments. **No deletes.**
  - `admin`: everything, including deletes.
- **A typo can't accidentally hand out more trust than you intended.** An invalid profile falls back to the safest option.

## What it can look up (always safe)

| What it covers | Examples |
| --- | --- |
| Contacts | Search and view contact records |
| Opportunities | View pipeline entries, pipelines and stages |
| Conversations | View message threads and individual messages |
| Calendar | View calendars, available booking slots, and existing appointments |

12 look-up actions in total.

## ⚠️ What it can change (off by default)

**`office-ops` level:**

| What it covers | Examples |
| --- | --- |
| Contacts | Create/update a contact, add a note |
| Opportunities | Create/update an opportunity, change its status |
| Conversations | Send a new SMS or email |
| Calendar | Book or reschedule an appointment |

**`admin` level only:**

- Deleting a contact, opportunity, or calendar event: GoHighLevel's API deletes are permanent, not a recoverable recycling bin

## How to set it up

No context-switching here. Do these three steps in order, and you won't need to jump back and forth.

You'll need a computer with [Node.js](https://nodejs.org) installed before you start.

### Step 1: Make a folder for this on your computer

Open Finder (Mac) or File Explorer (Windows), go to your Desktop or Documents, and create a new folder. Give it a name you'll recognize later, like `backcrew-mcp-gohighlevel`.

That's it for now. Just know where this folder is. Everything else gets put inside it.

### Step 2: Get your GoHighLevel credentials

Do this now, before touching the terminal:

1. Log into the specific GoHighLevel Location (sub-account) you want to connect
2. Go to **Settings → Private Integrations → Create New Integration**
3. Grant the scopes for the objects you want this server to touch (contacts, opportunities, conversations, calendars)
4. Copy the generated token, and note the Location ID (shown in your account settings)
5. Copy both values into a temporary note somewhere; you'll paste them in during Step 3

### Step 3: Install it

With your folder made and your credentials in hand, this is one continuous run; don't skip ahead or double back.

1. Open a terminal. On a Mac, press Cmd+Space, type "Terminal," and hit enter. On Windows, click the Start menu, type "PowerShell," and hit enter. Use PowerShell rather than Command Prompt: a couple of the commands below, like `pwd`, only work in PowerShell.
2. Type `cd ` (with a space after it), then drag your Step 1 folder from Finder/File Explorer straight into the terminal window; it'll paste the folder's path in automatically. Press enter.
3. Paste this exact command and press enter. It downloads the project directly into the folder you made (the trailing `.` matters, it means "put it here, not in a new folder"):
   ```bash
   git clone https://github.com/jayson-svg/backcrew-mcp-gohighlevel.git .
   ```
4. Paste this and press enter. It installs the project's dependencies:
   ```bash
   npm install
   ```
5. Paste this and press enter. It builds the project:
   ```bash
   npm run build
   ```
6. Paste this and press enter. It prints the full folder path. **Don't close this terminal window yet; you'll need this exact text in the next section.**
   ```bash
   pwd
   ```
7. Paste this and press enter. It creates your settings file from a template:
   ```bash
   cp .env.example .env
   ```
8. Open that new `.env` file in a text editor. On a Mac, paste `open -e .env` into the terminal and press enter. On Windows, paste `notepad .env` and press enter.
9. Find the lines for `GOHIGHLEVEL_PRIVATE_TOKEN=` and `GOHIGHLEVEL_LOCATION_ID=`. Paste in the matching values you collected in Step 2, right after each `=`, with no extra spaces or quotes.
10. Leave `GHL_MCP_MODE=read_only` and `GHL_MCP_PROFILE=readonly-owner` exactly as they are for now; that's the safe default. Save the file and close the editor.

## Connecting it to Claude

This step comes last on purpose; it needs the exact folder location from Step 3, and now you have it.

Open Claude's settings file (for Claude Desktop, `claude_desktop_config.json`) and add:

```json
{
  "mcpServers": {
    "gohighlevel": {
      "command": "node",
      "args": ["PASTE_YOUR_PWD_OUTPUT_HERE/dist/index.js"],
      "env": {
        "GOHIGHLEVEL_PRIVATE_TOKEN": "your_token_here",
        "GOHIGHLEVEL_LOCATION_ID": "your_location_id",
        "GHL_MCP_MODE": "read_only",
        "GHL_MCP_PROFILE": "readonly-owner"
      }
    }
  }
}
```

Replace `PASTE_YOUR_PWD_OUTPUT_HERE` with the exact text the `pwd` command printed back in Step 3 (keep the `/dist/index.js` part after it). If you're on Windows, swap any backslashes in that path for forward slashes (for example `C:/Users/yourname/Desktop/...` instead of `C:\Users\yourname\Desktop\...`), since the config file needs regular slashes.

Restart Claude. Also works with other MCP-compatible AI tools, including ChatGPT. If you're also running one of BackCrew's FSM servers, add both to the same config.

## Testing it safely

1. **Start in read-only mode and stay there for a while.**
2. **When you turn on `office-ops`, test on a clearly fake contact first.**
3. **Be extra careful with `send_message`.** Unlike most write actions in this series, sending an SMS or email reaches a real person immediately. Double-check the contact and content before sending, especially early on.
4. **Never go straight to `admin` mode.** GoHighLevel's API deletes are permanent.
5. **Never share your Private Integration Token.** Treat it like a password.
6. **If something looks wrong, switch back to `GHL_MCP_MODE=read_only` immediately.**

## For developers

Everything below this point assumes a coding background.

### Tool reference

Run the server and call `tools/list` to see exact schemas; every tool's description includes the GoHighLevel API path it maps to and its access tier.

### Project layout

```
src/
  index.ts          Server entrypoint
  client.ts          Minimal fetch-based GoHighLevel API client (Bearer auth, required Version header, error handling)
  toolkit.ts          Tier/profile-aware helper that wires a Zod input schema + handler into an MCP tool
  tools/
    contacts.ts
    opportunities.ts    (+ list_pipelines)
    conversations.ts
    calendar.ts
```

### The tier/profile system

Same pattern as the rest of this series: `GHL_MCP_MODE`/`GHL_MCP_PROFILE` gate what's registered at startup; `read_only` always wins; invalid profile falls back to the safest tier.

### Notes on the GoHighLevel API

- Base URL: `https://services.leadconnectorhq.com`. GoHighLevel's API runs under their white-label backend domain ("LeadConnector"), not gohighlevel.com
- Auth header: `Authorization: Bearer <token>` (works identically for both OAuth access tokens and Private Integration Tokens)
- Every request also needs a `Version: v3` header; confirmed directly and identically across every live endpoint page checked during this build (Create Contact, Create Opportunity, Send Message, Create Appointment)
- Most endpoints require a `locationId` (query param or body field, depending on the endpoint); this server reads it once from `GOHIGHLEVEL_LOCATION_ID` and includes it automatically, so individual tools don't ask for it
- Full reference: [marketplace.gohighlevel.com/docs](https://marketplace.gohighlevel.com/docs/) and the official public docs source repo, [GoHighLevel/highlevel-api-docs](https://github.com/GoHighLevel/highlevel-api-docs)

This server was built by reading GoHighLevel's public API documentation directly, endpoint by endpoint, with real field names and required-parameter rules confirmed against live documentation pages for Contacts, Opportunities, Conversations/Messages, and Calendar Events.

This repo intentionally stops at honest API access. It does not include business-logic features; those live in BackCrew's managed offering, not in this public repo. See [ROADMAP.md](ROADMAP.md).

## What's next

See [ROADMAP.md](ROADMAP.md) for the rest of the planned series and the pattern this repo follows.

## Built by BackCrew

This project is free and open for anyone to use, copy, or build on.

It's also a sample of the kind of work **BackCrew** does. If you want this expanded (workflow triggers, funnels, reputation management) or connected alongside a specific FSM server for your business, that's exactly the kind of project we take on.

**Want this done for you?** Reach out: **[jayson@backcrew.co](mailto:jayson@backcrew.co)**

No pressure either way. Everything above works on its own, for free.

## License

[MIT](LICENSE)