GTM ツール MCP (HG GTM Tools MCP)

HG Insights の GTM チーム（Sales、CS、Marketing、Product）向けの社内 MCP サーバー。Claude Desktop を介して、AI 支援のアウトリーチ作成、アカウント調査、カスタマーサポートの検索、管理機能を提供します。

MCP とは? Model Context Protocol — Claude Desktop がバックェンドツールの呼び出しに使う標準規格です。本リポジトリは、GTM に特化したツール（Salesforce の参照、Pylon の課題検索、アカウント調査など）を公開する MCP サーバーを記述しています。CSM が Claude Desktop に入力すると、Claude がここで定義されたツールを呼び出します。

Setup

前提条件: Python 3.11+、uv（インストール）、および環境変数を取得するための Railway CLI。Railway をまだ利用できない場合は #gtm-automation で問い合わせてください。

Railway CLI を初めて利用する場合は、以下の手順の前に railway login を実行し、ブラウザで認証を行ってください。

uv sync                                                                        # install deps
railway link -p 283ad9d5-e8d7-48d9-b380-10f9e5fab860 -e production             # link to hg-gtm-tools / production
railway variable list --kv > .env                                              # pull env values into a local .env
uv run pytest                                                                  # confirm setup works (37 tests, ~2s, no network)
uv run python -m src                                                           # run the server on http://localhost:8000/mcp

uv run pytest は、.env を用意する前のクローンした直後でも動作します — テストでは Clerk + Supabase + 上流の HTTP やりとりをスタブ化しています。本番遮環境の環境変数は、実際にサーバーを（python -m src）で起動したときだけ使われます。

本番: https://hg-gtm-tools-mcp.madkudu.ai/mcp 。マニフェストは /tools/manifest （認証なしで、登録済みの全ツールを一覧表示）で確認できます。プロジェクトルートから railway up でデプロイします — DEPLOYMENT.md を参照してください。

デプロイ後のライブスモークテスト: uv run pytest tests/live/ -v （初回は OAuth のためブラウザが開きます）。デフォルトの pytest 実行からは除外されています。

Related MCP server: Worksona MCP Server

Docs

まずはここから（コントリビューター向け）:

• ツールの追加 — 新ツールのエーンドツーエンドの歩き方

• テスト — フィクスチャとパターン

• ツール命名規約

• コントリビュート — コントリビュートフローの簡易リファレンス

リファレンス:

• アーキテクチャ — 認証フロー、非同期の受け渡し、レイヤーの責務

• デプロイ — railway up の仕組み、同期ジョブ

• 開発 — 研究パイプラインと API の落とし穴

• Super-Ops 本役 — 汎用 SOQL アクセス

• アーキテクチャ図 / MCP アプリ図（ブラウザで開く）

ツール

アウトリーチ作成（ops, csm, am, manager, marketing）: create_outreach_draft, update_outreach_draft, list_drafts

アウトリーチ閲覧（ops, csm, am, manager, marketing）: my_drafts, get_draft_detail, approve_draft, skip_draft

リサーチ（ops, csm, am, manager, marketing）: start_research, get_research_result, show_account_brief, get_account_detail

Book of Accounts（ops, csm, am, manager, marketing）: get_book_of_accounts, update_last_outbound, clear_last_outbound_override

HG Data Catalogs（ops, csm, am, manager, marketing）: hg_lookup_industry_codes, hg_lookup_intent, hg_lookup_products

HG Spend Categories（ops, csm, am, manager, marketing）: hg_get_spend_categories

TrustRadius インセンティブ予算（ops, csm, am, manager, marketing）: tr_get_incentive_budget

TrustRadius のレビューとキャンペーン（ops, csm, am, manager）: tr_search_vendors, tr_get_review_report, tr_get_campaign_report

Vitally Success Plans（ops, csm, am, manager, marketing）: vitally_show_success_plans, vitally_create_success_plan, vitally_update_success_plan

カスタマープロジェクト（ops, csm, am, manager, marketing）: list_customer_projects

連絡先検索（ops, csm, am, manager, marketing）: search_crm_contacts（郵便番号 + 半径）

連絡先ルックアップ（ops, csm, am, manager）: lookup_contact

Pylon（ops, csm, am, pm, manager, marketing）: pylon_search_accounts, pylon_search_issues, pylon_get_issue

Jira（ops, csm, am, pm, manager, marketing）: jira_search_tickets, jira_get_ticket

Weflow（ops, csm, am, pm, manager, marketing）: weflow_search_recordings, weflow_get_transcript

ナレッジベース（ops, csm, am, pm, manager, marketing）: kb_search, kb_read, kb_flag_gap

CSM 統計（ops, csm, am, manager）: get_csm_book_stats

ルックアップ（ops, csm, am, manager, marketing）: lookup_account

Google Slides（ops, csm, am, manager, pm, marketing）: google_slides

Admin（ops）: list_users, create_user, update_user, delete_user

Salesforce 連絡先変更（ops, csm, am, manager, marketing）: crm_update_contact, crm_create_contact。上書き保護と完全な監査ログ付きのデータ品質編集。

Super-Ops Salesforce（super_ops）: crm_soql_query, crm_describe_sobject, crm_soql_update。信頼済みオペレータ向けの汎用 SOQL 読み書きとスキーマ説明。すべての呼び出しが監査されます。docs/super-ops-role.md を参照してください。

プロジェクト構成

src/
├── server.py            # FastMCP server + Clerk OIDC auth
├── __main__.py          # Uvicorn entry point
├── auth.py              # Current user from JWT claims
├── roles.py             # Role-based tool filtering (VALID_ROLES)
├── usage.py             # @tracked audit-log decorator
├── manifest.py          # /tools.json manifest endpoint for the dashboard
├── db.py                # Supabase CRUD (sync + async variants)
├── storage.py           # Supabase-backed AsyncKeyValue for OAuth state
├── geo.py               # State/country normalization + zip radius
├── product_map.py       # ProductCode → category mapping
├── tools/               # MCP tool handlers (one file per source)
│   ├── _shared.py       # @tool decorator (the contributor entry point)
│   ├── _registry.py     # Auto-discovery: walks this dir at startup
│   └── *.py             # One file per source — see `ls src/tools/`
├── clients/             # Async upstream API clients (one per service)
├── apps/                # MCP app bundles (Vite + vite-plugin-singlefile)
├── research/            # Account research pipeline (orchestrator + agents)
├── kb/                  # Knowledge base sync + read endpoints
└── sync/                # Scheduled sync jobs

tests/
├── conftest.py          # mcp_client, fake_user, mock_audit_log, env stubs
├── fixtures/upstreams.py  # mock_jira, mock_pylon, mock_salesforce, etc.
└── test_*.py            # one file per tool module being tested

docs/
├── adding-a-tool.md     # end-to-end walkthrough for new contributors
├── testing.md           # fixture reference
└── *.md                 # design docs and references

tools/ ディレクトリは意図的にフラットにしています。データソースごとに 1 ファイル、起動時に自動検出されます。新しいツールを追加するときは、ここにファイルを置くだけで完了します。docs/adding-a-tool.md を参照してください。