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.

Runtime configuration is via environment variables.

| Variable | Required | Description | |---|---|---| | GOOGLE_APPLICATION_CREDENTIALS | Yes | Path to a Google credential JSON key file (service account or authorized-user — see Authentication below) | | 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. The only value read from disk is oauth.scope (in an optional config.json) — the single source of truth for the OAuth scope the onboarding paths request. If no config.json is present, the committed minimum scope is used.

Authentication

This MCP supports two auth models. Both feed the same GOOGLE_APPLICATION_CREDENTIALS runtime path.

Precedence & mechanism

There is no runtime service-account-vs-OAuth toggle. Both models converge on a single slot — GOOGLE_APPLICATION_CREDENTIALS — which the runtime hands to GoogleAuth({ keyFile }). Whichever file you point that env var at is the credential:

• a service-account JSON key (option 1 below), or
• the authorized_user keyfile the auth subcommand writes (option 2) — a file that plugs into the exact same slot.

So the only real precedence rule is failure handling: an explicitly-configured keyfile is used; when GOOGLE_APPLICATION_CREDENTIALS is unset the server fails loudly at startup with an onboarding error naming both the service-account path and the auth OAuth helper. It deliberately does not fall back to Google's Application Default Credentials (gcloud user creds / GCE metadata server) — no silent machine-local default, no silent runtime failover.

1. Service account (primary, recommended for unattended/server use)

Create a service account in your GCP project, download its JSON key, grant it the GTM container role (on the target GTM container) and GA4 property access, and point GOOGLE_APPLICATION_CREDENTIALS at the key file. No OAuth flow, no browser, no refresh token. This is the recommended path for headless/server/unattended deployments.

2. User OAuth (interactive, for users without a service account)

If you can't use a service account, mint a user credential with your own Google OAuth client (a "Desktop app" OAuth 2.0 Client ID created in your own GCP project — enable the Tag Manager API and the Google Analytics Admin + Data APIs). Two equivalent onboarding commands, both hardened with PKCE (RFC 7636, S256) and both requesting the scope from config.json (oauth.scope) so they never drift:

export GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
export GOOGLE_CLIENT_SECRET=your-client-secret

# Option A: write an authorized_user credential file directly
node dist/index.js auth --output ./gtm-ga4-credentials.json
# then set GOOGLE_APPLICATION_CREDENTIALS=./gtm-ga4-credentials.json

# Option B: the standalone helper (prints GOOGLE_REFRESH_TOKEN + a ready-to-save
# authorized_user JSON you can write to a file for GOOGLE_APPLICATION_CREDENTIALS)
node get-refresh-token.cjs

The refresh token / credential is written by you and read from your environment only. Nothing is shared and no OAuth client keyfile is bundled. Do not run the helper with stdout redirected to a shared log — the refresh token is printed to stdout by design.

OAuth scopes requested

The onboarding paths request exactly the scopes this MCP's tools use (from config.example.json → oauth.scope):

| Scope | Needed by | |---|---| | tagmanager.edit.containers | gtm_create_tag, gtm_update_tag, gtm_create_variable, gtm_update_variable, gtm_delete_variable, tag/trigger/variable reads | | tagmanager.edit.containerversions | gtm_create_version | | tagmanager.publish | gtm_create_version, gtm_preview (quick preview) | | analytics.readonly | gtm_ga4_run_report, gtm_ga4_realtime_report, gtm_ga4_list_custom_dimensions | | analytics.edit | gtm_ga4_create_custom_dimension |

tagmanager.readonly is intentionally not requested — the edit scopes already grant read access.

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