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:
pinowithpino-pretty - Transport: MCP SDK stdio transport
License
MIT
Author
Built by Mark Harnett / drak-marketing