@aiwerk/mcp-server-ghl

GoHighLevel(GHL) API용 MCP 서버입니다. 에이전시가 고객의 영업 파이프라인, 캘린더, 대화 및 캠페인을 운영하는 데 사용하는 CRM 및 마케팅 자동화 플랫폼입니다.

GHL의 공식 OpenAPI 3.0.0 사양에서 생성된 41개 도메인에 걸친 569개의 도구입니다.

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 Integrations에서 **Private Integration Token(PIT)**을 생성하세요. 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는 이미 하나의 위치에 범위가 지정되어 있으므로 569개 도구 중 430개는 locationId(또는 altId/altType)를 선택적 매개변수로 허용합니다. 호출 에이전트가 제공하지 않으면 서버는 GHL_LOCATION_ID로 대체합니다. 또한 기본값이 항상 토큰 자체의 범위와 일치하므로 다른 계정에서 복사하여 붙여넣은 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). 생성기는 매개변수가 경로 템플릿에서 명확히 사용되므로 필수 문자열 필드로 채웁니다. 이는 여기서 도입된 것이 아니라 상위 사양의 공백입니다.

• 속도 제한은 아직 실제 계정으로 측정되지 않았습니다. 클라이언트는 GHL이 보내는 Retry-After를 사용하여 429에서 재시도하지만, 임의의 숫자로 선제적으로 제한하지 않습니다. 잘못된 가정된 제한은 계정을 과소 사용하거나 성공했을 호출을 실패하게 만들 수 있습니다.

테스트

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.와 제휴하지 않았습니다.