gtm-mcp

A comprehensive Google Tag Manager MCP server for building, auditing, diagnosing, and fixing GTM implementations.

75 tools | 4 resources | 3 workflow prompts

Features

• Account & Container Management - List accounts, create containers, get installation snippets
• Workspace Management - Create workspaces, check status, sync changes
• Tag CRUD - Create, read, update, delete tags (GA4, Google Ads, custom HTML, etc.)
• Trigger CRUD - Manage all trigger types (pageview, custom event, click, form, scroll, etc.)
• Variable CRUD - Manage user-defined and built-in variables
• Folder Organisation - Create folders, move entities for container governance
• Version & Publishing - Create versions, compare with live, publish
• Version Diff & Rollback - Compare versions/workspace vs live, publish rollback
• Environment Management - Manage staging/dev environments
• User Permissions - Grant and modify account/container access
• Audit & Diagnosis - Container health scores, broken tag detection, duplicate finding, naming convention checks, trigger analysis, GA4 validation
• Consent Audit - Identify tags missing Consent Mode settings
• Server-side Clients - List and manage server-side GTM clients
• Google Ads Goals Audit - List conversion actions and map website goals to GTM setup
• GA4 Admin - List accounts/properties and create properties/streams
• Merchant Center - Account status checks, product listings, disapproval audits
• Builder Templates - One-command setup for GA4, Google Ads conversions, consent mode, custom events, enhanced ecommerce

Quick Start

1. Install

npm install -g gtm-mcp

Or run directly:

npx gtm-mcp

2. Configure Authentication

The server needs access to the Google Tag Manager API via a service account.

Option A: Service account key file (recommended)

export GTM_SERVICE_ACCOUNT_KEY_PATH="/path/to/service-account.json"

Option B: Inline JSON key

export GTM_SERVICE_ACCOUNT_KEY_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'

Option C: Application Default Credentials

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
# or run: gcloud auth application-default login

Service Account Setup

1. Go to Google Cloud Console
2. Create or select a project
3. Enable the Tag Manager API (tagmanager.googleapis.com)
4. Create a Service Account under IAM & Admin > Service Accounts
5. Create a JSON key for the service account
6. In GTM, grant the service account email access to your GTM account (Admin > User Management)

Google Ads (Optional)

To use Google Ads audit tools, configure OAuth credentials and a developer token:

export GOOGLE_ADS_DEVELOPER_TOKEN="your-dev-token"
export GOOGLE_ADS_CLIENT_ID="your-oauth-client-id"
export GOOGLE_ADS_CLIENT_SECRET="your-oauth-client-secret"
export GOOGLE_ADS_REFRESH_TOKEN="your-refresh-token"
export GOOGLE_ADS_CUSTOMER_ID="1234567890"
# Optional (manager account):
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="0987654321"

Multi-account: The GOOGLE_ADS_CUSTOMER_ID is just the default. You can query any client account per-call by passing customerId to the Google Ads tools. All accounts under your MCC are accessible without configuration changes.

Merchant Center (Optional)

To use Merchant Center tools, grant the service account access to your Merchant Center account and set:

export MERCHANT_CENTER_ID="123456789"

Merchant Center Quick Example

Prompt:

Audit Merchant Center disapprovals for merchant 123456789 and scan up to 1000 products.

Expected output shape:

{
  "summary": {
    "totalChecked": 1000,
    "disapprovedCount": 42,
    "issueCategories": 7,
    "truncated": false
  },
  "topIssues": {
    "invalid_gtin": {
      "count": 12,
      "description": "Invalid GTIN",
      "items": ["Product A", "Product B"]
    }
  },
  "recommendation": "Fix these issues in the primary feed or via supplemental feeds to restore product visibility."
}

GA4 Admin Quick Example

Prompt:

Create a GA4 property under accounts/123 and a web data stream for https://example.com.

Expected output shape (from ga4_create_data_stream):

{
  "message": "Data stream created successfully",
  "streamName": "Web Stream",
  "name": "properties/123/dataStreams/456",
  "measurementId": "G-ABCDEFG123",
  "instruction": "Use 'gtm_setup_ga4' with measurementId 'G-ABCDEFG123' to configure this in GTM."
}

3. Connect to Claude

Claude Desktop

Add gtm-mcp to your claude_desktop_config.json alongside any existing MCP servers:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gtm-mcp": {
      "command": "npx",
      "args": ["-y", "gtm-mcp"],
      "env": {
        "GTM_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-dev-token",
        "GOOGLE_ADS_CLIENT_ID": "your-oauth-client-id",
        "GOOGLE_ADS_CLIENT_SECRET": "your-oauth-client-secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "0987654321",
        "MERCHANT_CENTER_ID": "123456789"
      }
    }
  }
}

Restart Claude Desktop after saving. Google Ads and Merchant Center env vars are optional.

Claude Code

claude mcp add gtm-mcp npx -- -y gtm-mcp \
  -e GTM_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json

Add GOOGLE_ADS_* and MERCHANT_CENTER_ID env vars if you plan to use those tools.

Or add a .mcp.json file to your project root:

{
  "mcpServers": {
    "gtm-mcp": {
      "command": "npx",
      "args": ["-y", "gtm-mcp"],
      "env": {
        "GTM_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account.json"
      }
    }
  }
}

Add GOOGLE_ADS_* and MERCHANT_CENTER_ID env vars here if needed.

Claude.ai (Web)

Go to Settings > Integrations > Add Custom MCP Server and configure with command npx, args -y gtm-mcp, and the same environment variables.

Security note: Add .mcp.json to .gitignore to avoid committing credentials. Use .mcp.example.json as a template for others.

Tool Reference

Account & Container (5 tools)

| Tool | Description | |------|-------------| | gtm_list_accounts | List all accessible GTM accounts | | gtm_list_containers | List containers in an account | | gtm_get_container | Get container details | | gtm_create_container | Create a new container | | gtm_get_container_snippet | Get the GTM installation code snippet |

Workspace (4 tools)

| Tool | Description | |------|-------------| | gtm_list_workspaces | List workspaces in a container | | gtm_create_workspace | Create a new workspace | | gtm_get_workspace_status | Get pending changes in a workspace | | gtm_sync_workspace | Sync workspace with latest container version |

Tags (5 tools)

| Tool | Description | |------|-------------| | gtm_list_tags | List all tags in a workspace | | gtm_get_tag | Get full tag configuration | | gtm_create_tag | Create a tag | | gtm_update_tag | Update an existing tag | | gtm_delete_tag | Delete a tag |

Triggers (5 tools)

| Tool | Description | |------|-------------| | gtm_list_triggers | List all triggers in a workspace | | gtm_get_trigger | Get full trigger configuration | | gtm_create_trigger | Create a trigger | | gtm_update_trigger | Update an existing trigger | | gtm_delete_trigger | Delete a trigger |

Variables (7 tools)

| Tool | Description | |------|-------------| | gtm_list_variables | List user-defined variables | | gtm_get_variable | Get variable configuration | | gtm_create_variable | Create a variable | | gtm_update_variable | Update a variable | | gtm_delete_variable | Delete a variable | | gtm_list_built_in_variables | List enabled built-in variables | | gtm_enable_built_in_variables | Enable built-in variable types |

Server-side Clients (5 tools)

| Tool | Description | |------|-------------| | gtm_list_clients | List clients in a server-side workspace | | gtm_get_client | Get full client configuration | | gtm_create_client | Create a client | | gtm_update_client | Update a client | | gtm_delete_client | Delete a client |

Folders (3 tools)

| Tool | Description | |------|-------------| | gtm_list_folders | List folders in a workspace | | gtm_create_folder | Create a folder | | gtm_move_entities_to_folder | Move tags/triggers/variables into a folder |

Versions & Publishing (5 tools)

| Tool | Description | |------|-------------| | gtm_list_versions | List container versions | | gtm_get_version | Get full version details | | gtm_get_live_version | Get the currently published version | | gtm_create_version | Create a version from workspace changes | | gtm_publish_version | Publish a version to make it live |

Version Diff & Rollback (5 tools)

| Tool | Description | |------|-------------| | gtm_diff_versions | Compare two container versions | | gtm_diff_workspace_to_live | Compare workspace vs live version | | gtm_rollback_version | Roll back by publishing a prior version | | gtm_export_container_version | Export a container version snapshot | | gtm_import_container_version | Import a container version into a workspace |

Environments (3 tools)

| Tool | Description | |------|-------------| | gtm_list_environments | List environments | | gtm_create_environment | Create a custom environment | | gtm_update_environment | Update environment configuration |

Permissions (3 tools)

| Tool | Description | |------|-------------| | gtm_list_user_permissions | List user permissions on an account | | gtm_create_user_permission | Grant user access | | gtm_update_user_permission | Modify user permissions |

Audit & Diagnosis (7 tools)

| Tool | Description | |------|-------------| | gtm_audit_container | Comprehensive container audit with health score (0-100) | | gtm_find_broken_tags | Identify broken or misconfigured tags | | gtm_find_duplicate_tags | Detect redundant tracking | | gtm_check_naming_conventions | Analyse naming pattern consistency | | gtm_analyze_triggers | Check trigger configuration and usage | | gtm_validate_ga4_setup | GA4-specific configuration validation | | gtm_audit_consent_settings | Audit consent settings on tags |

Google Ads (2 tools)

| Tool | Description | |------|-------------| | gads_list_conversion_actions | List Google Ads conversion actions (supports per-call customerId override) | | gads_audit_goals | Audit goals and map website conversions to GTM (supports per-call customerId override) |

GA4 Admin (4 tools)

| Tool | Description | |------|-------------| | ga4_list_accounts | List GA4 accounts accessible to the service account | | ga4_list_properties | List GA4 properties (optionally filtered by account) | | ga4_create_property | Create a new GA4 property under an account | | ga4_create_data_stream | Create a GA4 web data stream and return the Measurement ID |

Merchant Center (3 tools)

| Tool | Description | |------|-------------| | gmc_get_account_status | Check Merchant Center account status and policy issues | | gmc_list_products | List products with status and item issues | | gmc_audit_disapprovals | Summarize disapproved products and root causes (supports maxResults) |

Example:

Audit Merchant Center disapprovals for merchant 123456789 and scan up to 1000 products.

Builder Templates (5 tools)

| Tool | Description | |------|-------------| | gtm_setup_ga4 | Create complete GA4 configuration (config tag + folder) | | gtm_setup_google_ads_conversion | Set up Google Ads conversion tracking | | gtm_setup_custom_event | Create custom event tracking (trigger + variables + GA4 event tag) | | gtm_setup_consent_mode | Implement Consent Mode v2 with privacy-first defaults | | gtm_setup_ecommerce | Set up enhanced ecommerce event tracking |

Resources

| Resource | URI | Description | |----------|-----|-------------| | Tag Types Reference | gtm://tag-types | GTM tag type identifiers and configuration | | Trigger Types Reference | gtm://trigger-types | GTM trigger types and filter options | | Variable Types Reference | gtm://variable-types | GTM variable types and configuration | | Naming Conventions | gtm://naming-conventions | Recommended naming convention guide |

Workflow Prompts

| Prompt | Description | |--------|-------------| | gtm_audit_workflow | Step-by-step container audit (health score, broken tags, duplicates, naming, triggers, GA4) | | gtm_setup_workflow | Guided new container setup (folders, variables, GA4, consent mode, snippet) | | gtm_debug_workflow | Troubleshooting workflow for diagnosing tracking issues |

Development

# Clone and install
git clone <repo-url>
cd gtm-mcp
npm install

# Build
npm run build

# Run in dev mode (with tsx)
npm run dev

# Run built version
npm start

License

MIT