@ainative/gtm-mcp

@ainative/gtm-mcp

Google Tag Manager MCP server — audit, fix, and manage GTM containers from AI agents.

Part of the AINative open-source tools.

24 tools across 6 categories: accounts, tags, triggers, audit, versions/publishing, and Google Ads.

Quick Start

1. Install

# Claude Code (recommended)
claude mcp add ainative-gtm-mcp npx -- -y @ainative/gtm-mcp \
  -e GTM_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json

# Or run directly
npx @ainative/gtm-mcp

2. Set up Google Cloud authentication

The server authenticates via a Google Cloud service account with Tag Manager API access. There is no browser OAuth flow — it's designed for headless/agent use.

Step 1 — Enable the Tag Manager API

• Go to Google Cloud Console
• Select or create a project
• Navigate to APIs & Services → Library
• Search for Tag Manager API (tagmanager.googleapis.com) and click Enable

Step 2 — Create a service account

• Go to IAM & Admin → Service Accounts
• Click Create Service Account
• Give it a name (e.g. gtm-mcp-agent)
• Skip role assignment at GCP level — GTM has its own permission system
• Click Done, then open the service account
• Go to Keys → Add Key → Create new key → JSON
• Download the JSON key file — keep it safe

Step 3 — Grant the service account access in GTM

This is the step most people miss. The GCP service account needs to be added as a user inside Google Tag Manager separately:

• Go to tagmanager.google.com
• Click Admin (top nav)
• Under Account, click User Management
• Click + → Add users
• Enter the service account email (e.g. [e-mail])
• Set permission to Publish (required for tag editing and publishing)
• Save

Note: If you only need read access (auditing), Read permission is sufficient.

Step 4 — Configure the env var

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

# Or use inline JSON (useful for CI/CD)
export GTM_SERVICE_ACCOUNT_KEY_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'

# Or use Application Default Credentials
gcloud auth application-default login

3. Connect to Claude Code

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

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

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

Security: Add .mcp.json to .gitignore if it contains key paths. Use .mcp.example.json as a template for teammates.

4. Verify it works

Ask Claude:

List my GTM accounts

Expected: your GTM account name and ID. If you get an empty array [], the service account hasn't been added to GTM yet (Step 3 above).

Important: GTM vs Google Ads conversions

This MCP server manages Google Tag Manager containers — tags, triggers, variables, and publishing.

If you see events like ads_conversion_PURCHASE_1 in GA4, those may be coming from Google Ads auto-imported conversions (via GA4 ↔ Google Ads account linking), not GTM tags. In that case:

• If the event fires via a GTM tag → use gtm_find_misfiring_conversion_tags to fix it
• If the event is a GA4-imported Google Ads conversion → fix it in Google Ads → Tools → Conversions, not in GTM

To tell the difference: if your GTM container has no tags (gtm_list_tags returns []), the conversion event is coming from outside GTM.

Example: Fix a misfiring conversion tag

The most common GTM billing issue — a Google Ads conversion tag fires on every page view instead of only on purchase confirmation.

1. List your accounts:
   "List my GTM accounts"
   → accountId: 123456789

2. List containers:
   "List containers for account 123456789"
   → containerId: 987654321, publicId: GTM-XXXXXXX

3. Audit the container:
   "Audit container 987654321 in account 123456789"
   → health score, list of issues including misfiring tags

4. Find misfiring conversion tags:
   "Find misfiring conversion tags in container 987654321"
   → shows which tags fire on All Pages instead of specific events

5. Fix the tag:
   "Fix tag 42 to only fire on the purchase_confirmed event"
   → gtm_fix_conversion_tag_trigger creates a scoped Custom Event trigger
     and rewires the tag automatically

6. Review and publish:
   "Show pending workspace changes, then publish"
   → gtm_get_workspace_status + gtm_publish

Tool Reference

Account & Container (3 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

Tags (4 tools)

Tool	Description
gtm_list_tags	List all tags in a workspace
gtm_get_tag	Get full tag configuration
gtm_update_tag	Update a tag (trigger, params, name)
gtm_delete_tag	Delete a tag

Triggers (4 tools)

Tool	Description
gtm_list_triggers	List all triggers
gtm_get_trigger	Get trigger configuration
gtm_create_trigger	Create a new trigger
gtm_update_trigger	Update an existing trigger

Audit & Fix (3 tools)

Tool	Description
gtm_audit_container	Full container audit — health score 0–100, issues list
gtm_find_misfiring_conversion_tags	Find conversion tags firing on All Pages instead of specific events
gtm_fix_conversion_tag_trigger	Fix a misfiring tag — creates scoped Custom Event trigger, rewires tag

Versions & Publishing (4 tools)

Tool	Description
gtm_list_workspaces	List workspaces
gtm_get_workspace_status	View pending changes before publishing
gtm_create_version	Create a named version from workspace changes
gtm_publish	Publish workspace to live

Google Ads (4 tools)

Tool	Description
gads_list_conversion_actions	List all conversion actions — name, ID, counting type, status, category
gads_update_conversion_counting	Fix counting type (ONE_PER_CLICK vs MANY_PER_CLICK) for a conversion action
gads_audit_conversion_goals	Audit all conversion goals — find misconfigured counting, inactive conversions
gads_get_account_performance	Account-level performance — impressions, clicks, cost, conversions by date range

Google Ads Authentication

The Google Ads tools use OAuth2 credentials. Provide them via environment variables or your ADC file:

# Option A: Explicit env vars
export GADS_CLIENT_ID="your-client-id"
export GADS_CLIENT_SECRET="your-client-secret"
export GADS_REFRESH_TOKEN="your-refresh-token"
export GOOGLE_ADS_DEVELOPER_TOKEN="your-developer-token"
export GOOGLE_ADS_CUSTOMER_ID="1234567890"

# Option B: Use Application Default Credentials (gcloud OAuth)
# Run: gcloud auth application-default login
# The server reads ~/.config/gcloud/application_default_credentials.json automatically
export GOOGLE_ADS_DEVELOPER_TOKEN="your-developer-token"
export GOOGLE_ADS_CUSTOMER_ID="1234567890"

Developer token: Get yours at Google Ads API Center. A test token works for sandbox accounts; a standard token is required for production.

Note on GA4-imported conversions: If you see events like ads_conversion_PURCHASE_1 in GA4 but gads_list_conversion_actions returns an empty list, those conversions are GA4-imported into Google Ads (configured under Google Ads → Tools → Conversions). They are not standalone conversion actions and must be managed through the Google Ads UI.

Troubleshooting

Symptom	Cause	Fix
gtm_list_accounts returns []	Service account not added to GTM	Add service account email in GTM → Admin → User Management
Tag Manager API has not been used error	API not enabled	Enable at console.cloud.google.com → APIs & Services → Tag Manager API
Permission denied on tag update	Service account has Read-only	Upgrade to Publish permission in GTM User Management
gtm_list_tags returns []	Workspace is empty (no tags published)	Check a different workspaceId, or confirm tags exist in GTM dashboard
Conversion event in GA4 but no matching GTM tag	Event comes from Google Ads auto-import	Fix in Google Ads → Tools → Conversions, not in GTM

Development

git clone https://github.com/AINative-Studio/core
cd packages/mcp-servers/ainative-gtm-mcp
npm install
npm run build
npm run dev

License

MIT — AINative Studio