ghl-context-mcp

일부러 작게 만든 GoHighLevel MCP 서버입니다. 여섯 개의 도구가 하나의 작업에만 맞춰져 있습니다. 바로 곧 대화할 상대가 누구인지 파악하는 일입니다.

왜 만들었는가

CRM 위에 에이전트를 올릴 때 흔히 나타나는 실패 패턴은 도구 표면이 너무 넓고 일반적이어서 원시 API JSON을 그대로 쏟아내는 것입니다. 모델이 잘못된 도구를 선택하고, 아무도 말로 꺼내지 않을 필드들로 컨텍스트 창을 소모하며, 가끔은 레코드를 만들거나 덮어씁니다. 이 서버는 그 반대의 선택을 합니다. 여섯 도구를 제공하되, 각각 에이전트가 연락처와 대화하려는 바로 그 순간에 맞게 범위를 한정합니다. 반환되는 모든 필드는 사람이 실제로 말할 만한 것이거나, 에이전트가 다음 호출에 그대로 넘겨줄 것입니다. 날짜 계산은 서버가 직접 하며, 쓰기 동작은 사용자가 직접 켜기 전까지 꺼져 있습니다. 좁은 표면이 넓은 표면보다 낫다는 주장은 측정 가능하며, 그걸 측정하기 위한 동반 벤치마크(mcp-tool-surface-bench)가 구축되고 있습니다.

Related MCP server: GHL MCP Server

도구

상한은 응답별 토큰 예산입니다. 응답이 한도를 넘어가면 빌드를 실패시키는 테스트가 있습니다. 여기서 "토케"은 무슨 뜻인지 DESIGN.md를 참조하세요.

사용법

이 서버는 MCP 서버이며, 의도한 사용자는 단말기를 보는 사람이 아니라 AI 에이전트입니다. 서버를 에이전트(Claude Code, Claude Desktop, 또는 MCP를 지원하는 런타임)에 연결한 다음, 평범한 언어로 에이전트에게 말하면 됩니다. 연락처를 찾고 그 컨텍스트를 가져올지 결정하는 것은 에이전트입니다.

Claude Code에서의 팀 빠른 시작

1. 저장소를 클론하고 설치 및 빌드합니다:

   npm install && npm run build

2. 자격 증명을 추가합니다:

   cp .env.example .env
   # then edit .env and fill in GHL_PIT and GHL_LOCATION_ID

3. Claude Code에서 폴더를 엽니다. 여기에는 체크된 .mcp.json을 읽고 ghl-context 서버를 제공하며, 한 번만 승인하면 됩니다. 서버는 시작할 때 .env를 불러오므로 토큰이 설정 파일에 저장될 일은 없습니다.

4. 영업 담당자가 하루 시작할 때 하는 것처럼 에이전트에게 말합니다:

   오늘 Marcus Halloway와 Priya Nair에게 전화할 거예요. 각각 전화 전에 브리핑을 주세요.

   에이전트가 각 연락처를 확인하고, 타임라인, 파이프라인 위치, 다가오는 일정을 가져와 브리핑으로 정리해서 돌려줍니다.

다른 MCP 클라이언트

어느 MCP 클라이언트든 stdio로 서버에 연결할 수 있습니다. 배포된 패키지는 클론이나 빌드가 필요 없습니다. Claude Desktop의 claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
    "ghl-context": {
      "command": "npx",
      "args": ["-y", "ghl-context-mcp"],
      "env": {
        "GHL_PIT": "pit-...",
        "GHL_LOCATION_ID": "your-sub-account-id"
      }
    }
  }
}

배포된 패키지 대신 로컬 체크아웃을 실행하려면 command를 node로, args를 빌드된 dist/index.js로 설정하세요.

환경 변수

토큰은 설정(Settings) → 통합(Integrations) → Private 통합(Private Integrations)에서 만들고, 범위는 contacts.readonly, contacts.write, opportunities.readonly, opportunities.write, calendars.readonly를 포함해야 합니다.

클라이언트 없이 살펴보기

MCP 클라이언트가 준비되어 있지 않더라도, 리포지토리에는 에이전트가 수행할 것과 동일한 시퀀스를 실행하고 브리핑을 출력하는 터미널 데모가 포함되어 있습니다:

npm run brief -- "Marcus Halloway"

이것은 가치를 보여주는 데모이지 제품이 아닙니다. 제품은 위의 에이전트 연결입니다.

소스에서

npm install
npm run build
npm test

npm test는 자격 증명 없이도 통과합니다. 실시간 확인(npm run live-check, npm run live-write-check)은 실제 .env가 필요합니다.

응답 형태

해석된 연락처:

{
  "resolution": "exact",
  "contact": {
    "contact_id": "NnAyKFnTSAVKg1amAArO",
    "name": "Marcus Halloway",
    "primary_phone": "+15551230010",
    "primary_email": "marcus.halloway@example.com",
    "tags": ["synthetic-seed"],
    "owner": null,
    "last_activity_at": null,
    "last_activity_summary": null
  }
}

모호한 일치에서는 추측하지 않고 후보를 반환합니다:

{
  "resolution": "ambiguous",
  "candidates": [
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230012",
      "primary_email": "jordan.wells@example.com",
      "last_activity_at": null
    },
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230013",
      "primary_email": "jordan.wells.cpa@example.com",
      "last_activity_at": null
    }
  ],
  "disambiguate_by": ["email", "primary_phone"],
  "instruction": "Ask the user which one, or call again with the exact email or phone."
}

모호한 것은 성공으로 취급합니다. 에러가 발생한 에이전트는 멈추지만, 후보 목록을 받은 에이전트는 계속 진행하여 사용자에게 어떤 연락처를 의미했는지 확인합니다.

오류

모든 오류는 하나의 형태입니다. 원시 HTTP 상태가 모델로 전달되지 않습니다.

설계 원칙

서버가 바탕을 둔 여덟 가지 규칙을 한 줄씩 정리했습니다. 더 긴 설명과 면접관이 묻기 좋은 추론은 DESIGN.md에 있습니다.

1. 도구 하나당 작업 하나. 설명에 "그리고"가 필요하면 두 개의 도구입니다.

2. 설명은 모델을 위해 씁니다. 언제 사용할지, 언제 사용하지 말아야 할지, 그리고 헷갈리는 비슷한 도구를 함께.

3. 원시 API 형태는 경계 밖으로 나가지 않습니다. 테스트로 강제합니다.

4. 오류는 명령형의 지침이며, 유효한 선택지를 나열합니다.

5. 모든 응답에는 토큰 상한이 있고, 빌드를 실패시키는 테스트가 있습니다.

6. 계산은 서버가 합니다: 나이, 기간, 상대 시간, 개수.

7. 쓰기 동작은 자신이 의존하는 상태를 확인하고, 불일치하면 크게 실패합니다.

8. 쓰기는 GHL_ALLOW_WRITES=true인 경우가 아니면 꺼져 있습니다.

좋지 않은 것

각 잘라냄은 의도적입니다.

제약

단일 로케이션, Private Integration Token 인증만, OAuth 없음. 페이지네이션은 도구별 최대치로 제한됨. 정지 감지 기능이 의미 있으려면 충분한 데이터가 필요하며, 현재는 GoHighLevel이 단계 이력을 노출하지 않으므로 고정된 대체값을 사용합니다. 전화번호 매칭은 미국 중심입니다. 토큰 상한은 근사 토큰이지 정확한 Claude 토큰이 아닙니다. GoHighLevel의 쓰기는 읽기에 비해 약 한 초 지연됩니다. 하나의 계정 형태에서 테스트했습니다.

License

MIT