Skip to main content
Glama
HighLevel Workflow Kit MCP Server

HighLevel Workflow Kit MCP Server

by scalperkid
README.md
# highlevel-workflow-kit

I build HighLevel workflows for a living. This kit lets an AI agent do that work with me: read a sub-account, plan the workflows, write them, publish them and then prove they actually run. Nothing goes live until I type the confirmation phrase.

There is a 2 minute video of it here: https://offers.jeff-lim.com/sync-orchestrator. Section two shows this kit.

## Why I built it

HighLevel's public API has no endpoints for building workflows. You can list them and add a contact to one, and that is it. Every workflow still gets built by hand in the builder, click by click, and that is where most of the mistakes happen: a trigger with no filter, a drip that keeps texting after the lead replies, a reminder anchored to the wrong time.

The builder itself talks to a private API. I captured that contract on live accounts, wrote it down in `CONTRACT.md`, and built a small MCP server on top of it. Now I describe the system, the agent drafts it, I approve the copy, and the kit writes it the same way the builder would.

## What it does

1. **Discover.** Reads a sub-account: pipelines and stage ids, calendars, users, phone numbers, existing workflows. Prints a bindings skeleton for a recipe.
2. **Audit.** Reads every workflow and flags what looks wrong: triggers with no filter, drips that never stop, reminders waiting from the wrong moment, steps pointing at workflows that no longer exist. Read-only.
3. **Plan.** A recipe turns a small bindings file into whole workflows. The plan comes back with every text and email written out so a human can approve the words first. Nothing is touched.
4. **Write.** Backs up every workflow in the sub-account, writes the plan as drafts, then reads each one back and checks the step chain is intact.
5. **Publish.** Only when asked, and only if every chain passed the read-back.
6. **Prove.** Creates a test contact called "Test Lead (kit, ignore)", enrolls it, waits, reports the card and the messages it produced, then deletes it.

Every write needs three things: the sub-account is on the config allowlist, writes are switched on, and the caller sends the exact confirmation phrase the plan returned, for example `CONFIRM INSTALL <locationId> meta-lead-system`. The allowlist is the only thing between the agent and a live account, so I keep it to the one sandbox I am working on.

## Recipes

- `meta-lead-system`: Meta lead to booked appointment. Instant text and email, follow-up until booked, booking handoff, reminders, reply handoff.
- `meta-cadence-reply`: Meta lead where the team books by phone. Long text and email cadence, every message is a binding.
- `meta-capi-stages`: sends pipeline stage changes and won deals back to Meta through the Conversions API.
- `missed-call-and-reviews`: missed call text-back with a team alert, plus a review request started by a tag.
- `website-lead-response`: website form lead into the same pipeline as the Meta leads.
- `webhook-lead-capture`: a custom landing page form posts to an inbound webhook, the lead is tagged and the team is emailed.
- `instant-text-alert`: instant text plus a team alert for a landing page form and its chat widget.
- `stage-followup-text`: text a lead after the team moves their card to a stage, if it is still there after a delay.
- `stage-stop-followup`: stops follow-up workflows once the card moves past the early stages.

Each recipe exports `BINDINGS_SCHEMA` with every field explained.

## How it works

- `src/agency-server.js` is the MCP server, one per agency, driven by a config file. Tools: `location_discover`, `location_audit`, `recipe_plan`, `recipe_install`, `recipe_prove`, plus low-level `workflow_*` tools for reading, listing, enrolling and single mutations.
- `src/installer.js` holds the shared logic behind the MCP and the CLI: discover, audit, plan, backup, install, verify, prove.
- `src/private-client.js` and `src/private-workflow-api.js` call the builder's private API. `src/official-extra.js` calls the official API for reads, contacts and enrollment.
- Auth is the signed-in user's own session. The `extension/` folder is a small Chrome extension that watches HighLevel's own API calls in that profile and hands the session token to a broker on `127.0.0.1`. The broker keeps it in memory only. Nothing is written to disk and nothing leaves the machine.
- `src/kit.js` is the same flow as a CLI, for when I want to run it by hand.

## How to run it

You need Node 20 or newer, Chrome, and a HighLevel login on the agency you test on. Use a sandbox sub-account.

```
npm ci
npm test                 # unit tests, offline
npm run smoke            # starts the MCP server and checks the tool list, offline

node src/kit.js init my-agency --host app.gohighlevel.com    # writes configs/my-agency.json and builds dist/wfmcp
```

Load `dist/wfmcp` in `chrome://extensions` (Developer mode, Load unpacked), sign in to HighLevel in that profile and keep any HighLevel tab open. Then:

```
node src/kit.js doctor   configs/my-agency.json <locationId>
node src/kit.js discover configs/my-agency.json <locationId>
node src/kit.js audit    configs/my-agency.json <locationId>
node src/kit.js install  configs/my-agency.json bindings/<file>.json --dry-run
node src/kit.js install  configs/my-agency.json bindings/<file>.json
node src/kit.js install  configs/my-agency.json bindings/<file>.json --publish --proof
```

To use it from Claude Code:

```
claude mcp add --scope local my-agency-ghl-workflows -- node <kit>/src/agency-server.js <kit>/configs/my-agency.json
```

`configs/example.json` and `bindings/example-meta-lead-system.json` show the shape with placeholder ids. `docs/SETUP.md` is the full step by step.

### Config and environment

- Config file (`configs/<agency>.json`): `host` (the domain you sign in on), `brokerPort` (32147 to 32159), `writeLocationAllowlist`, `experimentalWrites`, and `tokenInventory`. With `officialViaWebBearer: true` the signed-in session is the only credential needed.
- `GHL_KIT_PROOF_EMAIL`: email used for the test contact in a proof. Defaults to `test-lead@example.com`.
- `GHL_LOCATION_TOKEN_INVENTORY_PATH`: optional `{ locationId: token }` file when you use Private Integration Tokens instead of the session.
- `META_CAPI_TOKEN`: only for the `meta-capi-stages` recipe, the dataset access token for that run. It is never written to a bindings file.

Real configs, bindings, backups and run output are gitignored. Backups go to `~/.ghl-workflow-kit/backups/` because a workflow export can contain integration tokens.

## Status

Working. I use it on my own and client builds, always through a sandbox first. It rides a private API that HighLevel does not support, so it can break when they change the builder. That is why every install reads its workflows back before it will publish. The chain check only understands linear workflows, so branched recipes need a read-back by hand before publishing.

## License

MIT. Built by Jeff Lim, hello@jeff-lim.com.