HG GTM Tools MCP

Interner MCP-Server für die GTM-Teams von HG Insights (Sales, CS, Marketing, Produkt). Er ermöglicht KI-gestützte Outreach-Entwürfe, Kundensuche, Kundensupport-Abfragen und Verwaltung über Claude Desktop.

Was ist MCP? Model Context Protocol – der Standard, über den Claude Desktop Backend-Tools aufruft. Dieses Repo implementiert einen MCP-Server, der GTM-spezifische Tools bereitstellt (Salesforce-Abfragen, Pylon-Issue-Suche, Account-Recherche usw.). Wenn ein CSM in Claude Desktop tippt, ruft Claude die hier definierten Tools auf.

Einrichtung

Voraussetzungen: Python 3.11+, uv (Installation) und die Railway CLI zum Abrufen der Env-Werte. Noch kein Railway-Zugriff? Frag in #gtm-automation.

Erstes Mal mit der Railway CLI? Führe railway login aus, um dich vor den folgenden Schritten über den Browser zu authentifizieren.

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 funktioniert auf einem frischen Klon, bevor du .env befüllt hast – die Tests stubben Clerk + Supabase + externe HTTP-Aufrufe. Produktions-Umgebungsvariablen kommen erst zum Einsatz, wenn der Server tatsächlich läuft (python -m src).

Produktion: https://hg-gtm-tools-mcp.madkudu.ai/mcp. Manifest unter /tools/manifest (ohne Authentifizierung, listet jedes registrierte Tool). Deployment mit railway up aus dem Projektverzeichnis – siehe DEPLOYMENT.md.

Smoke-Test live nach dem Deployment: uv run pytest tests/live/ -v (öffnet beim ersten Lauf einen Browser für OAuth). Vom normalen pytest-Lauf ausgenommen.

Related MCP server: Worksona MCP Server

Dokumentation

Start hier (Pfad für Mitwirkende):

• Ein Tool hinzufügen – End-to-End-Anleitung für neue Tools

• Testen – Fixtures und Muster

• Namenskonventionen für Tools

• Mitwirken – Kurzreferenz für den Mitwirkungsprozess

Referenz:

• Architektur – Auth-Ablauf, asynchrone Übergabe, Verantwortung der Ebenen

• Deployment – wie railway up funktioniert, Cron-Jobs

• Entwicklung – Research-Pipeline + API-Stolperfallen

• Super-Ops-Rolle – generischer SOQL-Zugriff

• Architektur-Diagramm / MCP-App-Diagramm (im Browser öffnen)

Tools

Outreach-Erstellung (ops): create_outreach_draft, update_outreach_draft, list_drafts

Outreach-Anzeige (ops, csm, am, manager, marketing): my_drafts, get_draft_detail, approve_draft, skip_draft

Recherche (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-Datenkataloge (ops, csm, am, manager, marketing): hg_lookup_industry_codes, hg_lookup_intent, hg_lookup_products

HG-Ausgabenkategorien (ops, csm, am, manager, marketing): hg_get_spend_categories

TrustRadius-Incentive-Budget (ops, csm, am, manager, marketing): tr_get_incentive_budget

TrustRadius-Bewertungen und Kampagnen (ops, csm, am, manager): tr_search_vendors, tr_get_review_report, tr_get_campaign_report

Vitally-Erfolgspläne (ops, csm, am, manager, marketing): vitally_show_success_plans, vitally_create_success_plan, vitally_update_success_plan

Kundenprojekte (ops, csm, am, manager, marketing): list_customer_projects

Kontaktsuche (ops, csm, am, manager, marketing): search_crm_contacts (Postleitzahl + Radius-Umkreissuche)

Kontakt-Lookup (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

Wissensdatenbank (ops, csm, am, pm, manager, marketing): kb_search, kb_read, kb_flag_gap

CSM-Statistiken (ops, csm, am, manager): get_csm_book_stats

Lookup (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-Kontaktmutationen (ops, csm, am, manager, marketing): crm_update_contact, crm_create_contact. Datenqualitätsänderungen mit Überschreibschutz und vollständigem Audit-Log.

Super-Ops-Salesforce (super_ops): crm_soql_query, crm_describe_sobject, crm_soql_update. Generischer SOQL-Lese-/Schreibzugriff + Schema-Beschreibung für vertrauenswürdige Operatoren. Jeder Aufruf wird protokolliert. Siehe docs/super-ops-role.md.

Projektstruktur

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

Das Verzeichnis tools/ ist bewusst flach gehalten: eine Datei pro Upstream-Quelle, die beim Start automatisch erkannt wird. Um ein neues Tool hinzuzufügen, legst du hier einfach eine Datei ab. Siehe docs/adding-a-tool.md.