gtmos-mcp

Nur-Lese-CRM-Prüfung für Claude: Bewerten Sie die Datenintegrität, finden Sie doppelte Cluster und festgefahrenen Umsatz in Ihrer Umgebung mit Ihrem eigenen Token.

Ein MCP (Model Context Protocol)-Server, mit dem Claude Desktop, Claude Code oder jeder MCP-Host Ihr HubSpot-CRM prüfen kann. Er läuft in Ihrer Umgebung, liest mit Ihrem eigenen HubSpot-Token und kein neuer Anbieter berührt Ihre Daten. Jedes Tool ist von Grund auf schreibgeschützt: Dieses Paket schreibt nichts in ein CRM, versendet keine E-Mails und ruft keine andere Netzwerk-API als Ihren eigenen HubSpot-Endpunkt auf.

• Null Abhängigkeiten. Reines Python stdlib (dependencies = []). Nichts, das transitiv überprüft werden müsste.

• Nur-Lese. Zwei Tools, beide prüfend. Es werden keine Schreib-Berechtigungen für Ihr Token benötigt.

• Deterministische Bewertung. Kein LLM im Bewertungspfad; das Modell liest die Ergebnisse, es erfindet sie nicht.

• Funktioniert offline. Wenn Sie die Tools auf einen JSON-Export anstelle eines Live-Portals richten, erfolgt überhaupt kein Netzwerkaufruf.

Tools

Related MCP server: g-gremlin-hubspot-mcp

Installation

Erfordert Python 3.11+.

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

Überprüfung:

gtmos mcp --dry-run

Erwartete Ausgabe:

[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.

Verbinden mit Claude

Generieren Sie den Konfigurationsblock (entspricht immer dem installierten Code):

gtmos mcp --config

Fügen Sie ihn dann in Ihre MCP-Host-Konfiguration ein. Für Claude Desktop ist das ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Für Claude Code:

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

Starten Sie den Host neu und fragen Sie: "Prüfe mein CRM und zeige mir die schwächste Dimension."

Abrufen eines HubSpot-Tokens

Erstellen Sie eine private App in Ihrem HubSpot-Portal mit Nur-Lese-Berechtigungen: crm.objects.contacts.read für audit_crm, crm.objects.deals.read für funnel_leak. Das Token bleibt in Ihrer Host-Konfiguration auf Ihrem Rechner; dieses Paket speichert oder leitet es niemals weiter.

Kein Token? Verwenden Sie einen Export

Beide Tools akzeptieren eine Datei anstelle eines Live-Portals:

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

contacts.json ist ein JSON-Array von Kontaktobjekten (HubSpot-Export-Form: properties.email, properties.firstname, ...). Siehe tests/fixtures/contacts_sample.json und tests/fixtures/deals_sample.json für die genauen Formen.

Wie ein Durchlauf aussieht

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

CLI ohne MCP

Dieselben Engines laufen direkt von der Shell:

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

Architektur

Durch Zeilenumbrüche getrenntes JSON-RPC 2.0 über stdio, gemäß dem MCP-stdio-Transport. Der Protokoll-Handler (handle_message) ist eine reine Funktion, Nachricht rein, Antwort raus, sodass die gesamte Oberfläche testbar ist, ohne einen Prozess zu starten. Die Bewertungs-Engines sind deterministisch und netzwerkunabhängig; der einzige Netzwerk-Code ist der optionale HubSpot-Abruf, der mit Ihrem Token von Ihrem Rechner aus erfolgt.

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

Tests

python -m pytest tests/

59 Tests, alle offline, kein Token erforderlich.

Lizenz

MIT