Ainative Gtm Mcp

@ainative/gtm-mcp

Google Tag Manager and Google Ads MCP server — audit, fix, and manage GTM containers and Google Ads campaigns, budgets, conversions, placements, geo targeting, and auto-apply recommendations from AI agents (Claude, Cursor, and any MCP client).

Part of the AINative open-source tools.

57 tools across 7 categories: accounts, tags, triggers, audit, versions/publishing, and a complete Google Ads lifecycle (39 tools) — build, publish, track, and adjust campaigns end-to-end: create campaigns/ad groups/RSAs/RDAs/HTML5 ads, Performance Max, bidding strategy & bid control, ad extensions (sitelinks/callouts/snippets/call), audiences, offline gclid conversion import, geo/language targeting, budgets, placements, and auto-apply recommendations — fully programmatic, no UI required.

Keywords: google tag manager mcp, google ads mcp, gtm mcp server, google ads api mcp, conversion tracking mcp, campaign budget management, negative placement / click-fraud exclusion, geo targeting, auto-apply recommendations, recommendation subscriptions, conversion goals, Smart Bidding, PPC automation, ad spend control, Claude MCP, model context protocol, AI agent advertising tools.

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 directlynpx @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 Credentialsgcloud 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)

Tags (4 tools)

Triggers (4 tools)

Audit & Fix (3 tools)

Versions & Publishing (4 tools)

Google Ads (39 tools)

Full programmatic campaign lifecycle — an agent can build, launch, measure, and optimize a campaign end-to-end with no UI.

Build (campaigns, ad groups, ads, assets)

Bidding & bids

Ad control

Ad extensions (assets)

Audiences & conversions (attribution)

Conversions & reporting

Campaigns & budgets

Targeting & fraud protection

Auto-apply recommendations

Google Ads Authentication

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

# Option A: Explicit env varsexport 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 automaticallyexport 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

Development

git clone https://github.com/AINative-Studio/corecd packages/mcp-servers/ainative-gtm-mcpnpm installnpm run buildnpm run dev

License

MIT — AINative Studio