@ainative/gtm-mcp

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

Part of the AINative open-source tools.

20 tools across 5 categories: accounts, tags, triggers, audit, versions/publishing.

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

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

Step 2 — Create a service account

1. Go to IAM & Admin → Service Accounts
2. Click Create Service Account
3. Give it a name (e.g. gtm-mcp-agent)
4. Skip role assignment at GCP level — GTM has its own permission system
5. Click Done, then open the service account
6. Go to Keys → Add Key → Create new key → JSON
7. 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:

1. Go to tagmanager.google.com
2. Click Admin (top nav)
3. Under Account, click User Management
4. Click + → Add users
5. Enter the service account email (e.g. [email protected])
6. Set permission to Publish (required for tag editing and publishing)
7. 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 |

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