feat: add ghl-browser MCP server with 308 tools for full GHL UI automation - #4665
Open
Smannenbach wants to merge 8 commits into
Open
feat: add ghl-browser MCP server with 308 tools for full GHL UI automation#4665Smannenbach wants to merge 8 commits into
Smannenbach wants to merge 8 commits into
Conversation
… full GHL UI New Playwright-based MCP server providing browser automation for GHL features not accessible via REST API. 25 tool modules cover workflows, funnels, pipelines, campaigns, social media, blogs, forms, email builder, page builder, proposals, calendars, reporting, memberships, invoices, reputation, affiliates, settings, trigger links, snapshots, conversation AI, media library, tags/custom fields, and automation templates. Includes discovery harness scripts and results from initial API endpoint sweep, plus a comprehensive integration test that validates all 36 read-only tools against the live GHL dashboard (all passing).
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a Playwright-based GHL browser automation MCP server with persistent authentication and 130 tools.
Changes:
- Adds browser lifecycle, login, and tool registration infrastructure.
- Implements automation across 25 GHL feature modules.
- Adds discovery harnesses, captured results, and live smoke/integration tests.
Reviewed changes
Copilot reviewed 74 out of 75 changed files in this pull request and generated 18 comments.
Show a summary per file
| File | Description |
|---|---|
src/ghl-browser/.gitignore |
Excludes generated and sensitive files. |
src/ghl-browser/README.md |
Documents setup, login, and tools. |
src/ghl-browser/browser-state/.gitkeep |
Preserves the state directory. |
src/ghl-browser/package.json |
Defines package metadata and dependencies. |
src/ghl-browser/tsconfig.json |
Configures TypeScript compilation. |
src/ghl-browser/smoke-test.mjs |
Tests MCP initialization and registration. |
src/ghl-browser/integration-test.mjs |
Exercises read-only tools live. |
src/ghl-browser/discovery-harness.mjs |
Captures page network traffic. |
src/ghl-browser/discovery-harness-2.mjs |
Audits action-triggered requests. |
src/ghl-browser/discovery-harness-bundles.mjs |
Scans frontend bundles. |
src/ghl-browser/discovery-harness-forms.mjs |
Explores form-builder UI. |
src/ghl-browser/discovery-harness-forms-v2.mjs |
Extends form discovery. |
src/ghl-browser/discovery-harness-manifest.mjs |
Extracts the app manifest. |
src/ghl-browser/discovery-harness-state.mjs |
Extracts page state. |
src/ghl-browser/discovery-harness-ws.mjs |
Captures WebSocket activity. |
src/ghl-browser/src/browser.ts |
Manages browser sessions and navigation. |
src/ghl-browser/src/helpers.ts |
Defines shared tool helpers. |
src/ghl-browser/src/index.ts |
Implements the MCP stdio server. |
src/ghl-browser/src/login.ts |
Persists interactive login state. |
src/ghl-browser/src/tools/index.ts |
Aggregates tool modules. |
src/ghl-browser/src/tools/affiliates.ts |
Adds affiliate tools. |
src/ghl-browser/src/tools/automation-templates.ts |
Adds automation-template tools. |
src/ghl-browser/src/tools/blogs.ts |
Adds blog tools. |
src/ghl-browser/src/tools/calendar-config.ts |
Adds calendar tools. |
src/ghl-browser/src/tools/campaigns.ts |
Adds campaign tools. |
src/ghl-browser/src/tools/conversation-ai.ts |
Adds Conversation AI tools. |
src/ghl-browser/src/tools/discovery.ts |
Adds runtime discovery tools. |
src/ghl-browser/src/tools/email-builder.ts |
Adds email-builder tools. |
src/ghl-browser/src/tools/form-builder.ts |
Adds form-builder tools. |
src/ghl-browser/src/tools/funnels.ts |
Adds funnel tools. |
src/ghl-browser/src/tools/invoices.ts |
Adds invoice tools. |
src/ghl-browser/src/tools/media-library.ts |
Adds media-library tools. |
src/ghl-browser/src/tools/memberships.ts |
Adds membership tools. |
src/ghl-browser/src/tools/page-builder.ts |
Adds page-builder tools. |
src/ghl-browser/src/tools/pipelines.ts |
Adds pipeline tools. |
src/ghl-browser/src/tools/proposals.ts |
Adds proposal tools. |
src/ghl-browser/src/tools/reporting.ts |
Adds reporting tools. |
src/ghl-browser/src/tools/reputation.ts |
Adds reputation tools. |
src/ghl-browser/src/tools/settings.ts |
Adds settings tools. |
src/ghl-browser/src/tools/snapshots.ts |
Adds snapshot tools. |
src/ghl-browser/src/tools/social.ts |
Adds social-media tools. |
src/ghl-browser/src/tools/tags-fields.ts |
Adds tag and field tools. |
src/ghl-browser/src/tools/trigger-links.ts |
Adds trigger-link tools. |
src/ghl-browser/src/tools/utils.ts |
Adds browser utility tools. |
src/ghl-browser/src/tools/workflows.ts |
Adds workflow tools. |
src/ghl-browser/discovery-results/FINDINGS.md |
Summarizes discovery findings. |
src/ghl-browser/discovery-results/_summary.json |
Summarizes page captures. |
src/ghl-browser/discovery-results/_summary-triggers.json |
Summarizes action audits. |
src/ghl-browser/discovery-results/app-manifest-full.json |
Stores the discovered manifest. |
src/ghl-browser/discovery-results/blogs.json |
Stores blog capture data. |
src/ghl-browser/discovery-results/calendar-open-audit.json |
Stores calendar action data. |
src/ghl-browser/discovery-results/calendars.json |
Stores calendar capture data. |
src/ghl-browser/discovery-results/campaigns.json |
Stores campaign capture data. |
src/ghl-browser/discovery-results/contacts-search-audit.json |
Stores contact-search traffic. |
src/ghl-browser/discovery-results/contacts-state.json |
Stores contact page state. |
src/ghl-browser/discovery-results/contacts-ws.json |
Stores contact WebSocket data. |
src/ghl-browser/discovery-results/contacts.json |
Stores contact capture data. |
src/ghl-browser/discovery-results/conversations-ws.json |
Stores conversation WebSocket data. |
src/ghl-browser/discovery-results/conversations.json |
Stores conversation capture data. |
src/ghl-browser/discovery-results/dashboard-state.json |
Stores dashboard page state. |
src/ghl-browser/discovery-results/dashboard-ws.json |
Stores dashboard WebSocket data. |
src/ghl-browser/discovery-results/dashboard.json |
Stores dashboard capture data. |
src/ghl-browser/discovery-results/funnels.json |
Stores funnel capture data. |
src/ghl-browser/discovery-results/invoices-list-audit.json |
Stores invoice action data. |
src/ghl-browser/discovery-results/media-library.json |
Stores media capture data. |
src/ghl-browser/discovery-results/opportunities.json |
Stores opportunity capture data. |
src/ghl-browser/discovery-results/reporting-attribution-audit.json |
Stores reporting action data. |
src/ghl-browser/discovery-results/settings-company-audit.json |
Stores company-settings traffic. |
src/ghl-browser/discovery-results/settings-location-audit.json |
Stores location-settings traffic. |
src/ghl-browser/discovery-results/settings.json |
Stores settings capture data. |
src/ghl-browser/discovery-results/social-planner.json |
Stores social-planner data. |
src/ghl-browser/discovery-results/users-list-audit.json |
Stores user-list traffic. |
src/ghl-browser/discovery-results/workflows-open-first-audit.json |
Stores workflow action data. |
src/ghl-browser/discovery-results/workflows-state.json |
Stores workflow page state. |
src/ghl-browser/discovery-results/workflows.json |
Stores workflow capture data. |
Suppressed comments (3)
src/ghl-browser/src/tools/pipelines.ts:108
- This snapshot also ignores the required
pipelineNameand reads whichever board GHL opens by default, then labels the result with the requested name. Select and verify the requested pipeline before evaluating the board.
src/ghl-browser/src/tools/social.ts:94 - The scheduling handler accepts and returns
accountsbut never selects them at all. Scheduled posts will use GHL's current/default account selection, so the reported recipients can differ from the actual recipients. Apply and verify the requested accounts before scheduling.
src/ghl-browser/src/tools/reputation.ts:302 - The
platformfilter is read and echoed but never applied before collecting the aggregate score. Supplyinggoogleorfacebooktherefore returns all-platform metrics mislabeled as platform-specific. Apply the platform filter or filter the extracted score before returning.
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+17
to
+20
| "dependencies": { | ||
| "@modelcontextprotocol/sdk": "^1.0.4", | ||
| "playwright": "^1.58.0", | ||
| "dotenv": "^16.4.5" |
Comment on lines
+11
to
+15
| "scripts": { | ||
| "build": "tsc -p tsconfig.json", | ||
| "watch": "tsc -p tsconfig.json --watch", | ||
| "start": "node dist/index.js", | ||
| "login": "node dist/login.js" |
Comment on lines
+29
to
+31
| A Chromium window opens to `https://app.leadconnectorhq.com/`. Log in manually | ||
| with your GHL agency/user credentials. Once the dashboard appears, close the | ||
| window — the auth state is persisted to `./browser-state/`. |
Comment on lines
+76
to
+77
| const base = process.env.GHL_APP_URL || "https://app.leadconnectorhq.com"; | ||
| const url = path.startsWith("http") ? path : `${base}${path.startsWith("/") ? "" : "/"}${path}`; |
Comment on lines
+31
to
+32
| try { | ||
| const result = await handler((args || {}) as Record<string, unknown>); |
Comment on lines
+260
to
+263
| const reviewRow = page | ||
| .locator(`[class*="review"]:has-text("${reviewerName}"), [class*="Review"]:has-text("${reviewerName}")`) | ||
| .first(); | ||
| await reviewRow.click({ timeout: 5000 }); |
Comment on lines
+94
to
+99
| ghl_browser_create_workflow: async (args) => { | ||
| const name = String(args.name); | ||
| const { page, close } = await openPage(); | ||
| try { | ||
| return await withPageError(page, "workflows-create", async () => { | ||
| await gotoGhl(page, "/automation/workflows"); |
Comment on lines
+152
to
+155
| ghl_browser_add_workflow_node: async (args) => { | ||
| const name = String(args.workflowName); | ||
| const nodeType = String(args.nodeType); | ||
| const label = args.nodeLabel as string | undefined; |
Comment on lines
+198
to
+202
| try { | ||
| await pubBtn.click({ timeout: 3000 }); | ||
| } catch { | ||
| // publish step may already be active | ||
| } |
Comment on lines
+20
to
+21
| const SERVER = resolve(homedir(), "mcp-servers/src/ghl-browser/dist/index.js"); | ||
| const proc = spawn("node", [SERVER], { stdio: ["pipe", "pipe", "pipe"] }); |
…ering full GHL platform New modules: conversations, contacts, documents, payments, ecommerce, events, communities, copilot, custom objects, notifications, voice AI, power dialer, performance AI, and agency management. Updated integration test to exercise 60+ read-only tools across all 39 modules.
Author
Update: Expanded to 203 tools across 39 modulesAdded 14 new tool modules covering the remaining GHL platform areas:
Total: 203 tools across 39 modules, covering workflows, funnels, pipelines, campaigns, social, blogs, forms, email, pages, proposals, calendars, reporting, memberships, invoices, reputation, affiliates, settings, triggers, snapshots, conversation AI, media library, tags/fields, automation templates, conversations, contacts, documents, payments, ecommerce, events, communities, copilot, custom objects, notifications, voice AI, power dialer, performance AI, and agency management. Integration test updated to exercise 60+ read-only tools against live GHL. |
Add documentation for 14 new modules: conversations, contacts, documents, payments, ecommerce, events, communities, copilot, custom objects, notifications, voice AI, power dialer, performance AI, and agency management.
Author
Update: README now documents all 203 toolsAdded full documentation tables for all 39 modules. Each tool is listed with its name and description, organized by GHL feature area. Module summary (39 modules, 203 tools):
Bold = new in this update. Integration tested: 58/58 read-only tools passing against live GHL. |
… scoring) — 229 tools New browser-automation modules covering high-priority GHL feature gaps: - Dashboard Widgets (5 tools): overview KPIs, widget data, pipeline/appointment summaries - Calendar Bookings (6 tools): list, details, confirm, cancel, no-show, reschedule - SEO Management (5 tools): overview, page analysis, keyword tracking - Snippets (5 tools): CRUD for reusable content blocks - Contact Scoring (5 tools): scoring models, rules, contact scores All 68 read-only integration tests pass against live GHL (0 failures).
Author
v1.3.0 — 5 new modules, 229 tools totalAdded 26 tools across 5 new modules covering high-priority GHL feature gaps:
Integration test results: 68/68 read-only tools pass against live GHL (0 failures). Running totals:
|
…s 50 modules Add 6 new modules (29 tools) covering GHL's AI and location management: - Superagents: list, details, create, update, logs - AI Employees: list, details, create, update, toggle enable/disable - Agent Builder: blueprints, create, builder config, publish - Agent Studio: test sessions, run tests, metrics - Industry Agents: marketplace browse, install, uninstall - Location Settings: settings, feature toggles, domains Integration tests: 76/76 read-only tools pass against live GHL.
Smannenbach
changed the title
Author
v1.4.0 — AI suite + location settings, 258 tools totalAdded 29 tools across 6 new modules covering GHL's AI agent platform and location management:
Integration test results: 76/76 read-only tools pass against live GHL (0 failures). Running totals:
Remaining gaps (~25 federated apps)Attribution, Goals, Field Manager, Bulk Operations, Scheduler, QR Codes, Coupons, Courses UI, White-label Mobile App, Reseller, Marketplace, and a few others. These are lower-priority / niche areas. |
… modules Add 50 tools across 10 new modules covering high-priority GHL gaps: - Ad Publishing: campaigns, metrics, create, toggle (Facebook/Google) - Bulk Actions: bulk tag add/remove, field update, operation status - Chat Widget: config, update, toggle, embed code, departments - Content AI: settings, templates, generate, history, usage - Gift Cards: CRUD, transactions, activate/deactivate - Preference Management: categories, contact prefs, TCPA/GDPR compliance - Reseller: overview, clients, pricing, invoices - SaaS Mode: overview, plans, clients, billing summary - Platform Billing: invoices, payment method, usage, plan comparison - Store Catalog: products, categories, orders summary All 308 tools register cleanly. TypeScript compiles with zero errors.
Smannenbach
changed the title
Author
v1.5.0 — 10 high-priority modules, 308 tools totalAdded 50 tools across 10 new modules targeting the highest-priority uncovered GHL federated apps:
Running totals:
Remaining gaps (~50 federated apps)Lower-priority apps still uncovered: WordPress, Yext, Template Library, Brand Boards, Store Widgets, Wallet Kit, Domain Connect/Reselling, Countdown Timer, QR Codes, Schema Markup, Labs, Launchpad, Onboarding, Media Editor, Vibe Editor, Client Portal Builder, and various internal/utility apps. |
…modules New modules: WordPress, Yext, Template Library, QR Codes, Schema Markup, Store Widgets, Payment Links, Domain Connect, Client Portal, Membership Settings
Author
v1.6.0 — 358 tools across 70 modules (+50 tools, +10 modules)Added 10 mid-priority modules covering more GHL federated apps:
Cumulative totals:
All modules follow the established pattern: Playwright persistent browser context, 5 tools per module, screenshot-on-error debugging. |
New modules: Brand Boards, Wallet Kit, Domain Reselling, Countdown Timer, Labs, Launchpad, Knowledge Base, Estimates, Phone Integration, Marketplace
Author
v1.7.0 — 408 tools across 80 modules (+50 tools, +10 modules)Added 10 more modules covering mid-priority federated apps:
Cumulative totals:
~30 federated apps remain (mostly internal/utility apps like Vibe Editor, Media Editor, Email Preview, Redirect, External Tracking, etc.). Combined with the REST sibling server (584 tools), total coverage is now 992 tools across GHL. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
ghl-browser— Playwright-based browser automation covering GHL (GoHighLevel) features not accessible via the REST APInpm run login) saves auth state; subsequent MCP runs reuse stored cookiesModules
Setup
Test Plan
npm run build— zero errors)tools/list)