gtmos-mcp

Auditoría CRM de solo lectura para Claude: puntúa la integridad de los datos, encuentra clústeres duplicados e ingresos estancados, en tu entorno a través de tu propio token.

Un servidor MCP (Model Context Protocol) que permite a Claude Desktop, Claude Code o cualquier host MCP auditar tu CRM de HubSpot. Se ejecuta en tu entorno, lee con tu propio token de HubSpot y ningún nuevo proveedor toca tus datos. Cada herramienta es de solo lectura por construcción: nada en este paquete escribe en un CRM, envía correos ni llama a ninguna API de red que no sea tu propio endpoint de HubSpot.

• Cero dependencias. Python stdlib puro (dependencies = []). Nada que auditar transitivamente.

• Solo lectura. Dos herramientas, ambas de auditoría. No se necesitan ámbitos de escritura en tu token.

• Puntuación determinista. Sin LLM en la ruta de puntuación; el modelo lee los resultados, no los inventa.

• Funciona sin conexión. Apunta las herramientas a una exportación JSON en lugar de un portal en vivo y no se realiza ninguna llamada de red.

Herramientas

Related MCP server: g-gremlin-hubspot-mcp

Instalación

Requiere Python 3.11+.

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

Verifica:

gtmos mcp --dry-run

Salida esperada:

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

Conectar a Claude

Genera el bloque de configuración (siempre coincide con el código instalado):

gtmos mcp --config

Luego pégalo en la configuración de tu host MCP. Para Claude Desktop, eso es ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Para Claude Code:

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

Reinicia el host y luego pregunta: "Audita mi CRM y muéstrame la dimensión más débil."

Obtener un token de HubSpot

Crea una aplicación privada en tu portal de HubSpot con ámbitos de solo lectura: crm.objects.contacts.read para audit_crm, crm.objects.deals.read para funnel_leak. El token permanece en la configuración de tu host en tu máquina; este paquete nunca lo almacena ni lo reenvía.

¿Sin token? Usa una exportación

Ambas herramientas aceptan un archivo en lugar de un portal en vivo:

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

contacts.json es un array JSON de objetos de contacto (forma de exportación de HubSpot: properties.email, properties.firstname, ...). Consulta tests/fixtures/contacts_sample.json y tests/fixtures/deals_sample.json para las formas exactas.

Cómo se ve una ejecución

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 sin MCP

Los mismos motores se ejecutan directamente desde el 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

Arquitectura

JSON-RPC 2.0 delimitado por nueva línea sobre stdio, según el transporte stdio de MCP. El manejador de protocolo (handle_message) es una función pura, mensaje de entrada, respuesta de salida, por lo que toda la superficie es comprobable sin generar un proceso. Los motores de puntuación son deterministas y sin red; el único código de red es la obtención opcional de HubSpot, usando tu token, desde tu máquina.

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

Pruebas

python -m pytest tests/

59 pruebas, todas sin conexión, no se requiere token.

Licencia

MIT