GoHighLevel MCP Server

LLM 에이전트에게 GoHighLevel CRM에 대한 운영 제어를 부여하는 Model Context Protocol 서버입니다. GoHighLevel API v2를 기반으로 연락처, 파이프라인, 캘린더, 메시징, 인보이스, 결제를 포괄하는 24개 모듈의 114개 도구를 제공합니다.

문제

GoHighLevel은 소규모 에이전시의 기준 기록(system of record)입니다. 모든 고객, 모든 예약, 모든 인보이스가 이곳에 담깁니다. 실제로 하루를 잡아먹는 작업은 단일 CRM 액션이 아니라 액션들 사이의 이음새입니다. 촬영 일정이 확정되면 누군가는 기회(opportunity)를 만들고, 알맞은 파이프라인 단계로 옮기고, 그 연락처에 캘린더 슬롯을 예약하고, 인보이스를 작성하고, 메모를 남겨야 합니다. 각 단계는 클릭 30초의 일이 하고, 이 과정은 한 주에 여러 번 그리고 행해집니다.

그런 작업은 CRM에 닿을 수만 있다면 에이전트가 정확히 해낼 수 있는 일입니다. 이 서버가 바로 그 접근 채널입니다. GoHighLevel을 유형이 지정되고 주석이 달린 도구들로 노출해서, 에이전트가 지시문 한 문장에서 전체 체인을 처리할 수 있게 하면서도 파괴적이거나 외부로 향하는 단계는 승인을 위해 계속 표시되기마 합니다.

Related MCP server: GoHighLevel MCP Server

아키텍처

24개 도구 모듈이 stdio 위의 단일 McpServer에 등록됩니다. 모든 요청은 인증, 필수 Version 헤더, 쿼리 스트링 구성, 오류 형식을 책임지는 하나의 ghlRequest()를 거칩니다. 모듈은 시작 시 GHL_DISABLED_MODULES로 켜고 끌 수 있습니다. 이는 소리보다 더 중요한데, 114개 도구 정의는 에이전트가 사용자 요청의 한 조각도 읽기 전에 컨텍스트 윈도의 적용 부분을 차지하기 때문입니다. 예약만 처리하는 배포는 6개 모듈만 등록하고 나머지는 건너뛸 수 있습니다.

  MCP host (Claude Desktop / Claude Code)
          | stdio (JSON-RPC)
  +-------v--------------------------------------------+
  |  index.ts   MODULES registry, GHL_DISABLED_MODULES  |
  +-------+--------------------------------------------+
          |
  +-------v-----+ +---------------+ +-----------+ ......  24 modules
  |  contacts   | | opportunities | | invoices  |
  +-------+-----+ +-------+-------+ +-----+-----+
          |               |               |
          |               |         +-----v--------------+
          |               |         | billing-helpers.ts |
          |               |         |  businessDetails   |
          |               |         |  contactDetails    |
          |               |         |  sender resolution |
          |               |         +-----+--------------+
          +-------+-------+---------------+
                  |
        +---------v----------------------------+
        |  client.ts  ghlRequest()             |
        |   Bearer token + Version header      |
        |   status-specific error hints        |
        +---------+----------------------------+
                  |
          services.leadconnectorhq.com

모든 쓰기 도구에는 MCP 주석이 달려 있습니다. 17개는 destructiveHint로 표시되고, ghl_send_message / ghl_send_invoice는 실제 고객에게 연락을 닿으므로 외부 지향(outward-facing)으로 분류됩니다. 호스트는 호출을 승인하기 전에 그 점을 드러내며, 이는 인보이스를 초안만 만드는 에이전트와 실수로 거래처에 인보이스를 발송해버리는 에이전트를 구분하는 핵심입니다.

실제로 가장 까다로운 부분

인보이스 생성. 엔드포인트는 businessDetails와 contactDetails 블록을 요구하는데 문서는 두 블록을 너무 단순하게 설명합니다. 문서에 나온 것처럼 contactId에 라인 아이템 몇 개를 넘기면 어떤 필드가 문젠지도 알려주지 않는 유효성 검사 오류가 돌아옵니다. 두 블록 모두 전체 내용이 필요하며, businessDetails.phoneNo와 contactDetails.phoneNo가 필수입니다. 이메일에 전화번호가 없는 연락처는 아예 인보이스를 만들 수 없음을 뜻합니다.

실재로 더 나 것은 값이 *UI가 만들어 내는 것과 동일해야 인보이스가 수동으로 만든 것과 같지 보이는 합니다. 아닌면 다른 로고, 다른 조항, 번호 자798번이 다른 인보이스가 됩니다. 이렇 기본값이 예상대로의 좋은 자리인 Location 프로필 이<아니다> GET /invoices/settings 뒤에 있습니다. UI가 기본값을 채우 때 사용하는 바로 그 원천입니다.

src/tools/billing-helpers.ts는 두 블록을 모두 해석해서 도구 쪽에는 contactId만 있으면 되도록 해줍니다. 사업할 세부 정보는 네 가지 계층을 순서대로 내려가며 채워집니다 — 호출 별 인자, GHL_BUSINESS_* 환경 변수, 저장된 인보이스 설정, Location 프로필 — 각 계층은 위 계층이 남겨 둔 빈 부분만 메끄고여끄여 예니다. 연락처 정보는 조회해서 조합하며, name은 전체 이름, first+last, 회사명, 이메일, 전화 순으로 폴백됩니다. 이를 이유는 GoHighLevel이 빈 이레름을 거부하해 그실 CRM 레코드에 이레름이 흔이 없기 때니습니다. 두 경로 모 도한 GHL의 투误한 422를 저면으로 드러내지 않헤각자, 어느 필드가 없으하며 필드빠 공급하려면 무엇을 해야 하는지 명시하는 메시지를 던집니다. 각 회는 Location 별으로 memoize되어 인보이스스 10비을 만들וע도 설정을 10번이 아니다 1번만 가져옵니다.

다르게 하겠다면 하는 점

1. 테스트트가 없음니다. 4,000줄이데도 테으이 단하도 없습니다. billing-helpers의 폴백 체인은 고정된(fixture) 데이터에 대한 순수 로직입니다. 저장소에서 가앙 테스트하기 쉬은 장면의 의마 비용이 가앙 크기 때문입니다. 실패 모두가 잘못된 인보ひ이스가 고객에게 보내지 생은 것이라 그렇습니다.

2. 429 오류에 대한 재시도가 없습니다. ghlRequest)는 호출자에계 “요률 제한; 잠시 후 재요호” 라고 안알으면서 실제로 재요호하지 않습니다. 백오프는 에이젠트의 판단 때문에이 아닌 클라이언트에 있는 것입니다.

3. 슈가 모들은 수준의 가변 마이고 무효화가 없습니다. 호으트가 자우로재가작한하는 stdio 서버에게면 그것도맏지만, 로중에 살아 있는 프나세서로 바두는 순가 잘못됩니다. 사얄자 프로필을 고치면 것다가 반영되지 않습나다.

4. 응답이 전부ustrassignment Record<string, unknown>이습니다. GoHighLevel은 OpenAPI 스세크를 공효물니다. 여기서 트이프를 생생하면 일부의 실시간 오류가 컴파일 오류로 월나 변합나다.

5. 한 서버에 114개 도구는 너무가 많습니다. 모듈 토글으은 해결직은 아已經가이트니다. 더 좋은형태는 소규모 도구 모으비에 디즈커토리 메채이라 그I 조절가 실제 사용곟고 았는만금 비요을 지불하는 것이.

설정

Node 20+와 GoHighLevel 계자이 필요합니다.

1. PRIVATE IN치그라 션 토큰 만들기

설정 → Private Integrations → 새 인치그라쇼션 만들기. 사용할 도구에 맞는 범위(scopes)를 ; 최소으:

contacts.readonly, contacts.write, opportunities.readonly, opportunities.write, calendars.readonly, calendars/events.write, conversations.readonly, conversations/message.write, invoices.readonly, invoices.write, products.readonly, products.w테이, ocations/customFields.readoncontent, workflow.readonly

토근을 복사하 킬족하자 — 그것이 pit-로 시조합니다.

2. Location ID 찾기

설정 → Bu장C 프로필, 또는 내스보드 URL에 결정되 있습니다: .../ocation/<LOCATION_ID>/...

3. 발드

git clone <this-repo>
cd ghl-mcp
npm install
npm run build

4. MCP 호으트에 등록

{
  "mcpServers": {
    "gohighlevel": {
      "command": "node",
      "args": ["/absolute/path/to/ghl-mcp/dist/index.js"],
      "env": {
        "GHL_API_KEY": "pit-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}

호으트를 재시장합니다. 모든 지원되는 변화 (인보이스 비즈니스 블록과 모듈 토글)은 .현.엑 마풀를 참조하업자.

호으트 업이 서버를 보고 싶다면:

GHL_API_KEY=pit-... GHL_LOCATION_ID=... npm run inspect

"자동화 구성"에 대한 참고 사항

GoHighLevel의 API는 워크플로우 로직을 만들 수 없습니다 — involve builder은 UI 전유입니다. 공식은 방버은 워크플로우를 UI에서 한 번 만든 뒤, 그 id을 ghl_list_workflows로 찾고, ghl_add_contact_to_workflow로 연락처를 등록하는 것입니다.

도구 참조

라이선스

MIT — LICENSE를 참조하세요. GoHighLevel과 제휴하거나 승인로 되는 NOT가 아닙니다.