@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. gtm-mcp-agent@your-project.iam.gserviceaccount.com)
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