{"_id":"@aiwerk/mcp-server-ghl","_rev":"2-f695197fe278c24a285e67df83a6eead","name":"@aiwerk/mcp-server-ghl","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@aiwerk/mcp-server-ghl","version":"0.1.0","keywords":["mcp","mcp-server","gohighlevel","ghl","aiwerk","crm","marketing-automation"],"author":{"name":"AIWerk","email":"kontakt@aiwerk.ch"},"license":"MIT","_id":"@aiwerk/mcp-server-ghl@0.1.0","maintainers":[{"name":"agbergsmann","email":"kontakt@aiwerk.ch"}],"homepage":"https://aiwerkmcp.com","bugs":{"url":"https://github.com/AIWerk/mcp-server-ghl/issues"},"bin":{"mcp-server-ghl":"dist/src/server.js"},"dist":{"shasum":"f71eae107d5c5ed577432501c341a6e6c63f00da","tarball":"https://registry.npmjs.org/@aiwerk/mcp-server-ghl/-/mcp-server-ghl-0.1.0.tgz","fileCount":9,"integrity":"sha512-hbIuaRjFY7t8MaX2IUw4C/tB+++f0lI4ZxnybxYzu/oS/Q4iqWRBiQjzU96FrpyjoZS08oVGV5SskzgBGtG/LA==","signatures":[{"sig":"MEUCIC1v7JW48HTaPDOMc+0CD7izM6vKzF7L3t9qbiRhUbIAAiEA3ZKOyc7PUPLhcp3/qZXfXpGvlzm1J7bzV3k3KYLTLhM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":883479},"main":"dist/src/server.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"4827197fe1c42a74eb902f3d13389b9099ba2d8d","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc -p tsconfig.json","smoke":"node scripts/live-smoke.mjs","start":"node dist/src/server.js","predev":"npm run gen-version","pretest":"npm run gen-version && bash -c 'pkill -9 -f \"[m]cp-server-ghl/node_modules/.*vitest\" 2>/dev/null; pkill -9 -f \"[m]cp-server-ghl/node_modules/.*esbuild.*--service\" 2>/dev/null; true'","posttest":"bash -c 'pkill -9 -f \"[m]cp-server-ghl/node_modules/.*vitest\" 2>/dev/null; pkill -9 -f \"[m]cp-server-ghl/node_modules/.*esbuild.*--service\" 2>/dev/null; true'","prebuild":"npm run gen-version","gen-tools":"node scripts/generate-tools.mjs","gen-naming":"node scripts/gen-naming.mjs spec/apps spec/ghl-tool-naming.json","gen-version":"node scripts/gen-version.mjs","prepublishOnly":"bash scripts/prepublish-safety.sh && npm run build && npm test"},"_npmUser":{"name":"agbergsmann","email":"kontakt@aiwerk.ch"},"repository":{"url":"git+https://github.com/AIWerk/mcp-server-ghl.git","type":"git"},"_npmVersion":"10.9.4","description":"GoHighLevel (GHL) API MCP server. 576 tools generated from the official OpenAPI 3.0.0 specification.","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.19.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.1","typescript":"^5.5.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-ghl_0.1.0_1787598459318_0.10192893545113257","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aiwerk/mcp-server-ghl","version":"0.2.0","description":"GoHighLevel (GHL) API MCP server. 569 tools generated from the official OpenAPI 3.0.0 specification.","type":"module","main":"dist/src/server.js","bin":{"mcp-server-ghl":"dist/src/server.js"},"scripts":{"gen-version":"node scripts/gen-version.mjs","gen-naming":"node scripts/gen-naming.mjs spec/apps spec/ghl-tool-naming.json","gen-tools":"node scripts/generate-tools.mjs","prebuild":"npm run gen-version","build":"tsc -p tsconfig.json","start":"node dist/src/server.js","predev":"npm run gen-version","dev":"tsc --watch","pretest":"npm run gen-version && bash -c 'pkill -9 -f \"[m]cp-server-ghl/node_modules/.*vitest\" 2>/dev/null; pkill -9 -f \"[m]cp-server-ghl/node_modules/.*esbuild.*--service\" 2>/dev/null; true'","test":"vitest run","posttest":"bash -c 'pkill -9 -f \"[m]cp-server-ghl/node_modules/.*vitest\" 2>/dev/null; pkill -9 -f \"[m]cp-server-ghl/node_modules/.*esbuild.*--service\" 2>/dev/null; true'","smoke":"node scripts/live-smoke.mjs","prepublishOnly":"bash scripts/prepublish-safety.sh && npm run build && npm test"},"engines":{"node":">=18.0.0"},"keywords":["mcp","mcp-server","gohighlevel","ghl","aiwerk","crm","marketing-automation"],"author":{"name":"AIWerk","email":"kontakt@aiwerk.ch"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/AIWerk/mcp-server-ghl.git"},"homepage":"https://aiwerkmcp.com","bugs":{"url":"https://github.com/AIWerk/mcp-server-ghl/issues"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.19.1","zod":"^3.25.76"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.5.0","vitest":"^3.2.1"},"_id":"@aiwerk/mcp-server-ghl@0.2.0","gitHead":"2f83ac662b7b6afc8f5ac33e66b30f7b94888925","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-oSEjKxBASMZlsTa8SXBfV0RsuKY4ZwXyNAxVEQGqYKuVPONAfZMOwZTxIabmDHvtVqpacY5uhh8b1EElVuClew==","shasum":"10e32abe45bad5b187884106c4243cb25ff3a016","tarball":"https://registry.npmjs.org/@aiwerk/mcp-server-ghl/-/mcp-server-ghl-0.2.0.tgz","fileCount":9,"unpackedSize":936818,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAHW5Fbe34YMWnb1mh9JiVUhSKc1yOVoUHYirAA6ODnRAiEA5EGqV3YBJJI2uTyd1ElQVdBdbh/cACXe6E1+akbUIXc="}]},"_npmUser":{"name":"agbergsmann","email":"kontakt@aiwerk.ch"},"directories":{},"maintainers":[{"name":"agbergsmann","email":"kontakt@aiwerk.ch"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-ghl_0.2.0_1787612747468_0.2565298246722141"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-24T19:07:39.165Z","modified":"2026-08-24T23:05:47.821Z","0.1.0":"2026-08-24T19:07:39.505Z","0.2.0":"2026-08-24T23:05:47.647Z"},"bugs":{"url":"https://github.com/AIWerk/mcp-server-ghl/issues"},"author":{"name":"AIWerk","email":"kontakt@aiwerk.ch"},"license":"MIT","homepage":"https://aiwerkmcp.com","keywords":["mcp","mcp-server","gohighlevel","ghl","aiwerk","crm","marketing-automation"],"repository":{"type":"git","url":"git+https://github.com/AIWerk/mcp-server-ghl.git"},"description":"GoHighLevel (GHL) API MCP server. 569 tools generated from the official OpenAPI 3.0.0 specification.","maintainers":[{"name":"agbergsmann","email":"kontakt@aiwerk.ch"}],"readme":"# @aiwerk/mcp-server-ghl\n\nMCP server for the [GoHighLevel](https://www.gohighlevel.com) (GHL) API, the CRM and\nmarketing automation platform used by agencies to run their clients' sales pipelines,\ncalendars, conversations and campaigns.\n\n569 tools across 41 domains, generated from GHL's official OpenAPI 3.0.0 specification.\n\n```\nContacts       Opportunities   Conversations   Calendars      Invoices\nPayments       Workflows       Campaigns       Forms          Surveys\nFunnels        Blogs           Courses         Products       Store\nSocial Media   Ad Manager      SaaS API        Snapshots      Custom Fields\n```\n\n## Why generated\n\nEvery endpoint, HTTP verb, parameter and field name comes from the official\nspecification rather than from prose documentation, so the tool surface can't drift\nfrom what GHL actually accepts. What the specification can't tell you, which\nendpoints need an agency-level token instead of a location one, which API version an\nendpoint expects, which fields the docs forgot to mark required, is layered on top\nby hand. See [GHL specifics worth knowing](#a-few-ghl-specifics-worth-knowing).\n\n## Install\n\n```bash\nnpm install -g @aiwerk/mcp-server-ghl\n```\n\nRequires Node.js 18 or newer.\n\n## Authentication\n\nCreate a **Private Integration Token** (PIT) in the target location under\n*Settings > Private Integrations*. A PIT is scoped to one location, it is not an\nagency-wide credential, and most tools need to know which location they're acting on.\n\n```bash\nexport GHL_PIT_TOKEN=\"your-private-integration-token\"\nexport GHL_LOCATION_ID=\"your-location-id\"\n```\n\n## Usage\n\n### Claude Code\n\n```bash\nclaude mcp add ghl \\\n  --env GHL_PIT_TOKEN=your-token \\\n  --env GHL_LOCATION_ID=your-location-id \\\n  -- npx -y @aiwerk/mcp-server-ghl\n```\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"ghl\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aiwerk/mcp-server-ghl\"],\n      \"env\": {\n        \"GHL_PIT_TOKEN\": \"your-token\",\n        \"GHL_LOCATION_ID\": \"your-location-id\"\n      }\n    }\n  }\n}\n```\n\n### AIWerk hosted service\n\nInstall it from the catalogue at [aiwerkmcp.com](https://aiwerkmcp.com) and add your\ntoken in the interface. No local setup required.\n\n## Safety features\n\n### Dry run\n\n```bash\nexport GHL_DRY_RUN=1\n```\n\nEvery write (`POST`/`PUT`/`PATCH`/`DELETE`) is stopped before it reaches GHL and\nreturns a description of the request that would have been sent. Reads still work\nnormally.\n\n### Agency-only endpoints get a clear error, not a bare 401\n\n39 endpoints (snapshots, the SaaS API, agency OAuth token exchange, creating custom\nobjects) require an agency-level token. A location PIT gets a plain `401` from GHL for\nthese with no explanation in the body, the server knows which endpoints these are and\nreturns a message saying so, instead of making it look like a bad or expired token.\n\n### locationId is filled in automatically\n\nA PIT is already scoped to one location, so 430 of the 569 tools accept `locationId`\n(or `altId`/`altType`) as an *optional* parameter, if the calling agent doesn't supply\none, the server falls back to `GHL_LOCATION_ID`. This also means a tool call can't\naccidentally target the wrong location by a copy-pasted id from a different account,\nsince the default always matches the token's own scope.\n\n## Configuration\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `GHL_PIT_TOKEN` | required | Private Integration Token |\n| `GHL_LOCATION_ID` | required | Location the PIT is scoped to; default for `locationId`/`altId` params |\n| `GHL_API_BASE_URL` | `https://services.leadconnectorhq.com` | Override the host |\n| `GHL_API_TIMEOUT_MS` | `30000` | Per request timeout |\n| `GHL_DRY_RUN` | off | `1` blocks all writes |\n| `GHL_MAX_RATE_LIMIT_WAIT_MS` | `10000` | Longest wait before failing on a rate limit |\n| `GHL_ENABLED_TAGS` | all | Comma separated domain filter, for example `contacts,invoices` |\n\n### Narrowing the tool set\n\nAll 569 tools are registered by default. A client that prefers a smaller surface can\nrestrict the server to specific domains (domain names are hyphenated, e.g.\n`social-media-posting`, `ad-manager`):\n\n```bash\nexport GHL_ENABLED_TAGS=\"contacts,opportunities,conversations,calendars\"\n```\n\nUnknown domain names are reported on startup rather than silently ignored.\n\n## A few GHL specifics worth knowing\n\n- **The API version differs per endpoint, not globally.** GHL sends a `Version`\n  request header (`2021-07-28` or `2021-04-15`) that the server sets per call based on\n  what each endpoint actually expects, a wrong version returns a *different response\n  shape* silently, not an error, so there's no single default to fall back on. 29\n  endpoints send no version header at all; the server matches that too.\n- **A location PIT cannot call agency-only endpoints, ever, no scope fixes it.**\n  `snapshots/*`, `saas-api/*`, `oauth/locationToken`, `oauth/installedLocations`, and\n  creating custom objects (`POST /objects`) need an agency-level credential.\n- **11 endpoints in the official spec omit a path parameter's declaration** (e.g. a\n  `noteId` on some calendar/conversation routes, a `postId` on blogs, a `type` on\n  contacts). The generator fills these in as required string fields since the\n  parameter is clearly used in the path template, this is an upstream spec gap, not\n  something introduced here.\n- **Rate limits have not yet been measured against a live account.** The client\n  retries on `429` using whatever `Retry-After` GHL sends, but does not pre-emptively\n  throttle with an invented number, an assumed limit that's wrong would either\n  under-use the account or start failing calls that would have succeeded.\n\n## Testing\n\n```bash\nnpm test          # unit tests, mocked fetch\nnpm run smoke      # read only, against a live account\n```\n\n## Development\n\nThe tool layer is generated and must not be edited by hand:\n\n```bash\nnpm run gen-naming   # specification  ->  tool names\nnpm run gen-tools    # specification  ->  zod schemas and call sites\nnpm run build\n```\n\n## Licence\n\nMIT, see [LICENSE](LICENSE).\n\nBuilt by [AIWerk](https://aiwerkmcp.com). Not affiliated with GoHighLevel / HighLevel Inc.\n","readmeFilename":"README.md"}