gtmos-mcp

読み取り専用のCRM監査ツール for Claude: データ整合性のスコアリング、重複クラスターの検出、停滞した収益の特定を、あなたの環境で、あなた自身のトークンを使って行います。

MCP（Model Context Protocol）サーバーで、Claude Desktop、Claude Code、または任意のMCPホストがHubSpot CRMを監査できるようにします。あなたの環境で動作し、あなた自身のHubSpotトークンで読み取りを行い、新しいベンダーがデータに触れることはありません。すべてのツールは設計上読み取り専用です。このパッケージはCRMへの書き込み、メール送信、またはあなた自身のHubSpotエンドポイント以外のネットワークAPI呼び出しを一切行いません。

• 依存関係ゼロ。 純粋なPython標準ライブラリ（dependencies = []）。推移的に検証するものはありません。

• 読み取り専用。 2つのツール、どちらも監査です。トークンに書き込みスコープは不要です。

• 決定論的スコアリング。 スコアリングパスに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トランスポートに従い、改行区切りのJSON-RPC 2.0 over stdio。プロトコルハンドラ（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