gtmos-mcp

읽기 전용 CRM 감사 도구 for Claude: 데이터 무결성 점수 산출, 중복 클러스터 및 정체된 수익을 사용자 환경에서 자체 토큰을 통해 확인하세요.

Claude Desktop, Claude Code 또는 모든 MCP 호스트가 HubSpot CRM을 감사할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다. 사용자 환경에서 실행되며, 사용자의 HubSpot 토큰으로 데이터를 읽고, 새로운 공급업체가 데이터에 접근하지 않습니다. 모든 도구는 설계상 읽기 전용입니다. 이 패키지는 CRM에 쓰기, 메일 전송, 또는 사용자의 HubSpot 엔드포인트 외의 네트워크 API 호출을 수행하지 않습니다.

• 의존성 제로. 순수 Python 표준 라이브러리 (dependencies = []). 전이적 검증이 필요 없습니다.

• 읽기 전용. 두 가지 도구, 모두 감사용입니다. 토큰에 쓰기 범위가 필요하지 않습니다.

• 결정론적 점수 산출. 점수 경로에 LLM이 없습니다. 모델은 결과를 읽을 뿐, 결과를 생성하지 않습니다.

• 오프라인 작동. 라이브 포털 대신 JSON 내보내기 파일을 도구에 지정하면 네트워크 호출이 전혀 발생하지 않습니다.

도구

Related MCP server: g-gremlin-hubspot-mcp

설치

Python 3.11+ 필요.

pip install git+https://github.com/Kai8karma/gtmos-mcp.git

확인:

gtmos mcp --dry-run

예상 출력:

[dry-run] gtmos mcp would serve 2 tools on stdio (protocol 2025-06-18)
  - audit_crm: Score a CRM export or live HubSpot portal for data-integrity leaks.
  - funnel_leak: Analyse deals by stage to find stalled pipeline and where revenue leaks out of the funnel.

Claude에 연결

설정 블록 생성 (항상 설치된 코드와 일치):

gtmos mcp --config

그런 다음 MCP 호스트 설정에 붙여넣으세요. Claude Desktop의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)입니다:

{
  "mcpServers": {
    "gtmos": {
      "command": "gtmos",
      "args": [
        "mcp"
      ],
      "env": {
        "GTMOS_HUBSPOT_TOKEN": "<your-hubspot-private-app-token>"
      }
    }
  }
}

Claude Code의 경우:

claude mcp add gtmos --env GTMOS_HUBSPOT_TOKEN=<your-hubspot-private-app-token> -- gtmos mcp

호스트를 재시작한 후, 다음과 같이 요청하세요: "내 CRM을 감사하고 가장 취약한 차원을 보여줘."

HubSpot 토큰 얻기

HubSpot 포털에서 읽기 전용 범위의 비공개 앱을 생성하세요: audit_crm용 crm.objects.contacts.read, funnel_leak용 crm.objects.deals.read. 토큰은 사용자 머신의 호스트 설정에만 저장됩니다. 이 패키지는 토큰을 저장하거나 전달하지 않습니다.

토큰이 없나요? 내보내기 파일 사용

두 도구 모두 라이브 포털 대신 파일을 허용합니다:

audit_crm  { "contacts_file": "./contacts.json", "acv": 9000 }
funnel_leak { "deals_file": "./deals.json" }

contacts.json은 연락처 객체의 JSON 배열입니다 (HubSpot 내보내기 형식: properties.email, properties.firstname, ...). 정확한 형식은 tests/fixtures/contacts_sample.json 및 tests/fixtures/deals_sample.json을 참조하세요.

실행 결과 예시

Scored 25 records.
Portal integrity score: 77.5 (B).
Duplicate clusters found: 2.
Dimension averages (worst first):
  - freshness: 55.0
  - ownership: 88.0
  - validity: 91.9
  - consistency: 93.6
  - completeness: 94.6
Full report written to: ./audit-out/integrity-report.md

MCP 없는 CLI

동일한 엔진이 셸에서 직접 실행됩니다:

gtmos audit --input contacts.json --acv 9000     # contact integrity audit
gtmos calibrate --scores s.json --outcomes o.json # grade the scorer against real outcomes

아키텍처

MCP stdio 전송 방식에 따라 stdio를 통한 개행으로 구분된 JSON-RPC 2.0입니다. 프로토콜 핸들러(handle_message)는 순수 함수로, 메시지 입력에 대한 응답 출력이므로 프로세스를 생성하지 않고도 전체 표면을 테스트할 수 있습니다. 점수 산출 엔진은 결정론적이며 네트워크가 필요 없습니다. 유일한 네트워크 코드는 사용자 머신에서 사용자 토큰을 사용하는 선택적 HubSpot 데이터 가져오기입니다.

gtmos/
  mcp/        stdio server + tool definitions
  audit/      contact integrity engine, fetch, report
  funnel/     deal-stage leak engine, fetch, report
  calibrate/  scorer-vs-reality grading

테스트

python -m pytest tests/

59개의 테스트, 모두 오프라인, 토큰 불필요.

라이선스

MIT