@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 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 (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)

Tool	Description
gads_create_campaign	Create a Search/Display campaign with a dedicated budget + correct network settings
gads_create_pmax_campaign	One-call Performance Max builder — campaign + budget + asset group (headlines, descriptions, images, logo) in a single call; Google's AI optimizes across Search/Display/YouTube/Gmail
gads_create_ad_group	Create an ad group inside a campaign
gads_create_responsive_search_ad	Create an RSA (3–15 headlines, 2–4 descriptions, length-validated)
gads_create_responsive_display_ad	Create a responsive display ad
gads_create_html5_ad	Create an HTML5 upload (animated) display ad from a media bundle
gads_upload_image_asset	Upload an image asset by URL
gads_upload_media_bundle	Upload an HTML5 media-bundle (zip) asset

Bidding & bids

Tool	Description
gads_set_bidding_strategy	Swap bidding strategy (Maximize Clicks / Maximize Conversions / Target CPA / Target ROAS / Manual CPC) — reads back the change to confirm it landed (empty-payload swaps silently no-op)
gads_set_ad_group_bid	Set an ad group's default max CPC bid
gads_set_keyword_bid	Set a specific keyword's max CPC bid

Ad control

Tool	Description
gads_set_ad_status	Pause / enable / remove an individual ad
gads_request_ad_review	Request re-review (appeal) of a disapproved/limited ad where API-appealable; honest result for UI-only policy topics

Ad extensions (assets)

Tool	Description
gads_add_sitelink	Create + attach a sitelink
gads_add_callout	Create + attach a callout (e.g. "7-Day Free Trial")
gads_add_structured_snippet	Create + attach a structured snippet
gads_add_call_extension	Create + attach a call (phone) extension

Audiences & conversions (attribution)

Tool	Description
gads_add_audience_to_ad_group	Attach a user-list audience (observation or targeting)
gads_create_conversion_action	Create an offline (UPLOAD_CLICKS) conversion action for gclid import
gads_upload_click_conversion	Upload an offline conversion keyed by gclid — ties a real signup back to the ad click that drove it

Conversions & reporting

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_set_conversion_goal_inclusion	Include/exclude a conversion action from the primary Conversions metric & Smart Bidding (e.g. stop a PAGE_VIEW action inflating conversions)
gads_get_account_performance	Account-level performance — impressions, clicks, cost, conversions by date range

Campaigns & budgets

Tool	Description
gads_update_campaign_budget	Set a campaign's daily budget (scale spend up or down)
gads_pause_campaign	Pause a campaign — stop ad serving immediately
gads_create_keyword	Add a keyword to an ad group
gads_remove_keyword	Remove (pause) a keyword from an ad group

Targeting & fraud protection

Tool	Description
gads_remove_campaign_criterion	Remove a campaign criterion (targeted geo/placement/keyword) by ID — e.g. stop targeting a country sending invalid traffic
gads_add_negative_placement	Exclude a website/app placement (block click-fraud sites like quiz farms and junk apps)
gads_add_geo_target	Add a geo target (presence-only by default — the India-fraud-safe setting)
gads_set_presence_only	Force presence-only geo targeting on a campaign
gads_add_negative_keyword	Add a campaign-level negative keyword
gads_add_language_target	Add a language target to a campaign

Auto-apply recommendations

Tool	Description
gads_list_recommendation_subscriptions	List auto-apply recommendation subscriptions and their status (audit what auto-applies)
gads_set_recommendation_subscription	Turn auto-apply recommendations ON/OFF (pause budget/bid recommendations that can silently raise spend)

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