@aiwerk/mcp-server-ghl

MCP-сервер для API GoHighLevel (GHL) — CRM и платформы автоматизации маркетинга, которую агентства используют для управления воронками продаж, календарями, разговорами и кампаниями своих клиентов.

569 инструментов в 41 домене, сгенерированных из официальной спецификации GHL OpenAPI 3.0.0.

Contacts       Opportunities   Conversations   Calendars      Invoices
Payments       Workflows       Campaigns       Forms          Surveys
Funnels        Blogs           Courses         Products       Store
Social Media   Ad Manager      SaaS API        Snapshots      Custom Fields

Почему сгенерировано

Каждая конечная точка, HTTP-глагол, параметр и имя поля взяты из официальной спецификации, а не из текстовой документации, поэтому поверхность инструментов не может отклониться от того, что GHL действительно принимает. То, что спецификация не может сообщить — какие конечные точки требуют токен уровня агентства вместо токена уровня локации, какую версию API ожидает конечная точка, какие поля документация забыла пометить как обязательные — добавляется вручную поверх. См. особенности GHL, которые стоит знать.

Related MCP server: GoHighLevel MCP Server

Установка

npm install -g @aiwerk/mcp-server-ghl

Требуется Node.js 18 или новее.

Аутентификация

Создайте Private Integration Token (PIT) в целевой локации в разделе Settings > Private Integrations. PIT привязан к одной локации, это не учетные данные уровня агентства, и большинству инструментов нужно знать, с какой локацией они работают.

export GHL_PIT_TOKEN="your-private-integration-token"
export GHL_LOCATION_ID="your-location-id"

Использование

Claude Code

claude mcp add ghl \
  --env GHL_PIT_TOKEN=your-token \
  --env GHL_LOCATION_ID=your-location-id \
  -- npx -y @aiwerk/mcp-server-ghl

Claude Desktop

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["-y", "@aiwerk/mcp-server-ghl"],
      "env": {
        "GHL_PIT_TOKEN": "your-token",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}

Хостируемый сервис AIWerk

Установите его из каталога на aiwerkmcp.com и добавьте свой токен в интерфейсе. Локальная настройка не требуется.

Функции безопасности

Пробный запуск

export GHL_DRY_RUN=1

Каждая операция записи (POST/PUT/PATCH/DELETE) останавливается до того, как достигнет GHL, и возвращает описание запроса, который был бы отправлен. Чтение работает в обычном режиме.

Конечные точки только для агентства возвращают понятную ошибку, а не голый 401

39 конечных точек (снимки, SaaS API, обмен токенами OAuth агентства, создание пользовательских объектов) требуют токен уровня агентства. Локационный PIT получает от GHL обычный 401 без объяснения в теле ответа; сервер знает, какие это конечные точки, и возвращает сообщение об этом, вместо того чтобы это выглядело как неверный или истекший токен.

locationId заполняется автоматически

PIT уже привязан к одной локации, поэтому 430 из 569 инструментов принимают locationId (или altId/altType) как необязательный параметр; если вызывающий агент не указывает его, сервер использует GHL_LOCATION_ID. Это также означает, что вызов инструмента не может случайно нацелиться на неправильную локацию из-за скопированного идентификатора из другого аккаунта, поскольку значение по умолчанию всегда соответствует области действия токена.

Конфигурация

Сужение набора инструментов

Все 569 инструментов регистрируются по умолчанию. Клиент, предпочитающий меньшую поверхность, может ограничить сервер конкретными доменами (имена доменов пишутся через дефис, например social-media-posting, ad-manager):

export GHL_ENABLED_TAGS="contacts,opportunities,conversations,calendars"

Неизвестные имена доменов сообщаются при запуске, а не молча игнорируются.

Несколько особенностей GHL, которые стоит знать

• Версия API различается для каждой конечной точки, а не глобально. GHL отправляет заголовок запроса Version (2021-07-28 или 2021-04-15), который сервер устанавливает для каждого вызова на основе того, что ожидает конкретная конечная точка; неверная версия возвращает другую форму ответа молча, а не ошибку, поэтому нет единого значения по умолчанию. 29 конечных точек вообще не отправляют заголовок версии; сервер это тоже учитывает.

• Локационный PIT не может вызывать конечные точки только для агентства, никогда, никакая область действия это не исправит. snapshots/*, saas-api/*, oauth/locationToken, oauth/installedLocations и создание пользовательских объектов (POST /objects) требуют учетные данные уровня агентства.

• 11 конечных точек в официальной спецификации пропускают объявление параметра пути (например, noteId в некоторых маршрутах календаря/разговоров, postId в блогах, type в контактах). Генератор заполняет их как обязательные строковые поля, поскольку параметр явно используется в шаблоне пути; это пробел в вышестоящей спецификации, а не что-то введённое здесь.

• Ограничения скорости ещё не измерены на реальном аккаунте. Клиент повторяет попытки при 429, используя Retry-After, который отправляет GHL, но не ограничивает заранее выдуманным числом; предполагаемый лимит, который окажется неверным, либо недоиспользовал бы аккаунт, либо начал бы отклонять вызовы, которые могли бы пройти.

Тестирование

npm test          # unit tests, mocked fetch
npm run smoke      # read only, against a live account

Разработка

Слой инструментов генерируется и не должен редактироваться вручную:

npm run gen-naming   # specification  ->  tool names
npm run gen-tools    # specification  ->  zod schemas and call sites
npm run build

Лицензия

MIT, см. LICENSE.

Создано AIWerk. Не аффилировано с GoHighLevel / HighLevel Inc.