mcp-gtm-ga4

MCP server for Google Tag Manager and GA4 -- tag management, consent auditing, workspace versioning, and analytics reporting via Claude.

Features

• 14 tools spanning GTM workspace management (tags, triggers, variables), consent compliance auditing, workspace preview/versioning, and GA4 reporting
• Sandbox safety -- all write operations verify they target the resolved workspace, refusing to write to non-sandbox workspaces
• Multi-client support -- configure per-client via environment variables
• Auto-detects Default Workspace ID -- no need to manually specify workspace IDs unless using a custom sandbox

Installation

npm install mcp-gtm-ga4

Or clone and build:

git clone https://github.com/mharnett/mcp-gtm-ga4.git
cd mcp-gtm-ga4
npm install
npm run build

Configuration

Security: Never share your .mcp.json file or commit it to git -- it may contain API credentials. Add .mcp.json to your .gitignore.

All configuration is via environment variables. No config.json file is needed.

Variable	Required	Description
GOOGLE_APPLICATION_CREDENTIALS	Yes	Path to a GCP service account JSON key file
GTM_ACCOUNT_ID	Yes	GTM account ID
GTM_CONTAINER_ID	Yes	GTM container ID
GA4_PROPERTY_ID	Yes	GA4 property ID
GTM_SANDBOX_WORKSPACE_ID	No	Override workspace ID (auto-detects Default Workspace if omitted)
MCP_SERVER_NAME	No	Server name (defaults to package name mcp-gtm-ga4)

See config.example.json for a reference template.

Usage

Claude Code (.mcp.json)

{
  "mcpServers": {
    "gtm-ga4": {
      "command": "node",
      "args": ["/path/to/mcp-gtm-ga4/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
        "GTM_ACCOUNT_ID": "1234567890",
        "GTM_CONTAINER_ID": "9876543",
        "GA4_PROPERTY_ID": "331956119"
      }
    }
  }
}

npx

GTM_ACCOUNT_ID=1234567890 \
GTM_CONTAINER_ID=9876543 \
GA4_PROPERTY_ID=331956119 \
GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json \
npx mcp-gtm-ga4

Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Safety

Workspace sandbox protection

All write operations (gtm_update_tag, gtm_create_tag, gtm_preview, gtm_create_version) verify they target the resolved workspace before executing. If a request attempts to write to a different workspace, the server returns a SafetyError and blocks the operation.

This prevents accidental production changes when the MCP server is configured against a sandbox workspace.

Tools

GTM Tags

Tool	Description
gtm_list_tags	List all tags in the workspace with consent status and firing triggers
gtm_get_tag	Get full tag configuration by tag ID
gtm_update_tag	Update an existing tag (merge patch via JSON)
gtm_create_tag	Create a new tag from a JSON definition

GTM Structure

Tool	Description
gtm_list_triggers	List all triggers (ID, name, type)
gtm_list_variables	List all variables (ID, name, type)

GTM Consent

Tool	Description
gtm_audit_consent	Audit all tags for consent configuration compliance

GTM Workspace

Tool	Description
gtm_preview	Generate a quick preview of the current workspace
gtm_create_version	Create a new container version from the workspace

GA4 Reports

Tool	Description
gtm_ga4_run_report	Run a GA4 report with dimensions, metrics, date range, and filters
gtm_ga4_realtime_report	Run a GA4 realtime report (last 30 minutes)

GA4 Admin

Tool	Description
gtm_ga4_list_custom_dimensions	List all custom dimensions for the property
gtm_ga4_create_custom_dimension	Create a new custom dimension

Architecture

• GTM API: googleapis (Tag Manager v2)
• GA4 Data: @google-analytics/data (BetaAnalyticsDataClient)
• GA4 Admin: @google-analytics/admin (AnalyticsAdminServiceClient)
• Resilience: cockatiel (retry, circuit breaker, timeout policies)
• Logging: pino with pino-pretty
• Transport: MCP SDK stdio transport

License

MIT

Author

Built by Mark Harnett / drak-marketing