{
  "markdown": "# @ainative/gtm-mcp\n\nGoogle 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).\n\nPart of the [AINative open-source tools](https://ainative.studio).\n\n**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.\n\n**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.\n\n## Quick Start\n\n### 1. Install\n\n```bash\n# Claude Code (recommended)\nclaude mcp add ainative-gtm-mcp npx -- -y @ainative/gtm-mcp \\\n  -e GTM_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json\n\n# Or run directly\nnpx @ainative/gtm-mcp\n```\n\n### 2. Set up Google Cloud authentication\n\nThe 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.\n\n#### Step 1 — Enable the Tag Manager API\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Select or create a project\n3. Navigate to **APIs & Services → Library**\n4. Search for **Tag Manager API** (`tagmanager.googleapis.com`) and click **Enable**\n\n#### Step 2 — Create a service account\n\n1. Go to **IAM & Admin → Service Accounts**\n2. Click **Create Service Account**\n3. Give it a name (e.g. `gtm-mcp-agent`)\n4. Skip role assignment at GCP level — GTM has its own permission system\n5. Click **Done**, then open the service account\n6. Go to **Keys → Add Key → Create new key → JSON**\n7. Download the JSON key file — keep it safe\n\n#### Step 3 — Grant the service account access in GTM\n\nThis is the step most people miss. The GCP service account needs to be added as a user **inside Google Tag Manager** separately:\n\n1. Go to [tagmanager.google.com](https://tagmanager.google.com)\n2. Click **Admin** (top nav)\n3. Under **Account**, click **User Management**\n4. Click **+** → **Add users**\n5. Enter the service account email (e.g. `gtm-mcp-agent@your-project.iam.gserviceaccount.com`)\n6. Set permission to **Publish** (required for tag editing and publishing)\n7. Save\n\n> **Note:** If you only need read access (auditing), **Read** permission is sufficient.\n\n#### Step 4 — Configure the env var\n\n```bash\nexport GTM_SERVICE_ACCOUNT_KEY_PATH=\"/path/to/service-account.json\"\n\n# Or use inline JSON (useful for CI/CD)\nexport GTM_SERVICE_ACCOUNT_KEY_JSON='{\"type\":\"service_account\",\"project_id\":\"...\",\"private_key\":\"...\"}'\n\n# Or use Application Default Credentials\ngcloud auth application-default login\n```\n\n### 3. Connect to Claude Code\n\n```bash\nclaude mcp add ainative-gtm-mcp npx -- -y @ainative/gtm-mcp \\\n  -e GTM_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json\n```\n\nOr add a `.mcp.json` to your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"ainative-gtm-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ainative/gtm-mcp\"],\n      \"env\": {\n        \"GTM_SERVICE_ACCOUNT_KEY_PATH\": \"/path/to/service-account.json\"\n      }\n    }\n  }\n}\n```\n\n> **Security:** Add `.mcp.json` to `.gitignore` if it contains key paths. Use `.mcp.example.json` as a template for teammates.\n\n### 4. Verify it works\n\nAsk Claude:\n```\nList my GTM accounts\n```\n\nExpected: 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).\n\n---\n\n## Important: GTM vs Google Ads conversions\n\nThis MCP server manages **Google Tag Manager containers** — tags, triggers, variables, and publishing. \n\nIf 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:\n\n- If the event fires via a GTM tag → use `gtm_find_misfiring_conversion_tags` to fix it\n- If the event is a GA4-imported Google Ads conversion → fix it in **Google Ads → Tools → Conversions**, not in GTM\n\nTo tell the difference: if your GTM container has no tags (`gtm_list_tags` returns `[]`), the conversion event is coming from outside GTM.\n\n---\n\n## Example: Fix a misfiring conversion tag\n\nThe most common GTM billing issue — a Google Ads conversion tag fires on every page view instead of only on purchase confirmation.\n\n```\n1. List your accounts:\n   \"List my GTM accounts\"\n   → accountId: 123456789\n\n2. List containers:\n   \"List containers for account 123456789\"\n   → containerId: 987654321, publicId: GTM-XXXXXXX\n\n3. Audit the container:\n   \"Audit container 987654321 in account 123456789\"\n   → health score, list of issues including misfiring tags\n\n4. Find misfiring conversion tags:\n   \"Find misfiring conversion tags in container 987654321\"\n   → shows which tags fire on All Pages instead of specific events\n\n5. Fix the tag:\n   \"Fix tag 42 to only fire on the purchase_confirmed event\"\n   → gtm_fix_conversion_tag_trigger creates a scoped Custom Event trigger\n     and rewires the tag automatically\n\n6. Review and publish:\n   \"Show pending workspace changes, then publish\"\n   → gtm_get_workspace_status + gtm_publish\n```\n\n---\n\n## Tool Reference\n\n### Account & Container (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `gtm_list_accounts` | List all accessible GTM accounts |\n| `gtm_list_containers` | List containers in an account |\n| `gtm_get_container` | Get container details |\n\n### Tags (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `gtm_list_tags` | List all tags in a workspace |\n| `gtm_get_tag` | Get full tag configuration |\n| `gtm_update_tag` | Update a tag (trigger, params, name) |\n| `gtm_delete_tag` | Delete a tag |\n\n### Triggers (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `gtm_list_triggers` | List all triggers |\n| `gtm_get_trigger` | Get trigger configuration |\n| `gtm_create_trigger` | Create a new trigger |\n| `gtm_update_trigger` | Update an existing trigger |\n\n### Audit & Fix (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `gtm_audit_container` | Full container audit — health score 0–100, issues list |\n| `gtm_find_misfiring_conversion_tags` | Find conversion tags firing on All Pages instead of specific events |\n| `gtm_fix_conversion_tag_trigger` | Fix a misfiring tag — creates scoped Custom Event trigger, rewires tag |\n\n### Versions & Publishing (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `gtm_list_workspaces` | List workspaces |\n| `gtm_get_workspace_status` | View pending changes before publishing |\n| `gtm_create_version` | Create a named version from workspace changes |\n| `gtm_publish` | Publish workspace to live |\n\n### Google Ads (39 tools)\n\nFull programmatic campaign lifecycle — an agent can build, launch, measure, and optimize a campaign end-to-end with no UI.\n\n**Build (campaigns, ad groups, ads, assets)**\n\n| Tool | Description |\n|------|-------------|\n| `gads_create_campaign` | Create a Search/Display campaign with a dedicated budget + correct network settings |\n| `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 |\n| `gads_create_ad_group` | Create an ad group inside a campaign |\n| `gads_create_responsive_search_ad` | Create an RSA (3–15 headlines, 2–4 descriptions, length-validated) |\n| `gads_create_responsive_display_ad` | Create a responsive display ad |\n| `gads_create_html5_ad` | Create an HTML5 upload (animated) display ad from a media bundle |\n| `gads_upload_image_asset` | Upload an image asset by URL |\n| `gads_upload_media_bundle` | Upload an HTML5 media-bundle (zip) asset |\n\n**Bidding & bids**\n\n| Tool | Description |\n|------|-------------|\n| `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) |\n| `gads_set_ad_group_bid` | Set an ad group's default max CPC bid |\n| `gads_set_keyword_bid` | Set a specific keyword's max CPC bid |\n\n**Ad control**\n\n| Tool | Description |\n|------|-------------|\n| `gads_set_ad_status` | Pause / enable / remove an individual ad |\n| `gads_request_ad_review` | Request re-review (appeal) of a disapproved/limited ad where API-appealable; honest result for UI-only policy topics |\n\n**Ad extensions (assets)**\n\n| Tool | Description |\n|------|-------------|\n| `gads_add_sitelink` | Create + attach a sitelink |\n| `gads_add_callout` | Create + attach a callout (e.g. \"7-Day Free Trial\") |\n| `gads_add_structured_snippet` | Create + attach a structured snippet |\n| `gads_add_call_extension` | Create + attach a call (phone) extension |\n\n**Audiences & conversions (attribution)**\n\n| Tool | Description |\n|------|-------------|\n| `gads_add_audience_to_ad_group` | Attach a user-list audience (observation or targeting) |\n| `gads_create_conversion_action` | Create an offline (UPLOAD_CLICKS) conversion action for gclid import |\n| `gads_upload_click_conversion` | Upload an offline conversion keyed by gclid — ties a real signup back to the ad click that drove it |\n\n**Conversions & reporting**\n\n| Tool | Description |\n|------|-------------|\n| `gads_list_conversion_actions` | List all conversion actions — name, ID, counting type, status, category |\n| `gads_update_conversion_counting` | Fix counting type (ONE_PER_CLICK vs MANY_PER_CLICK) for a conversion action |\n| `gads_audit_conversion_goals` | Audit all conversion goals — find misconfigured counting, inactive conversions |\n| `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) |\n| `gads_get_account_performance` | Account-level performance — impressions, clicks, cost, conversions by date range |\n\n**Campaigns & budgets**\n\n| Tool | Description |\n|------|-------------|\n| `gads_update_campaign_budget` | Set a campaign's daily budget (scale spend up or down) |\n| `gads_pause_campaign` | Pause a campaign — stop ad serving immediately |\n| `gads_create_keyword` | Add a keyword to an ad group |\n| `gads_remove_keyword` | Remove (pause) a keyword from an ad group |\n\n**Targeting & fraud protection**\n\n| Tool | Description |\n|------|-------------|\n| `gads_remove_campaign_criterion` | Remove a campaign criterion (targeted geo/placement/keyword) by ID — e.g. stop targeting a country sending invalid traffic |\n| `gads_add_negative_placement` | Exclude a website/app placement (block click-fraud sites like quiz farms and junk apps) |\n| `gads_add_geo_target` | Add a geo target (presence-only by default — the India-fraud-safe setting) |\n| `gads_set_presence_only` | Force presence-only geo targeting on a campaign |\n| `gads_add_negative_keyword` | Add a campaign-level negative keyword |\n| `gads_add_language_target` | Add a language target to a campaign |\n\n**Auto-apply recommendations**\n\n| Tool | Description |\n|------|-------------|\n| `gads_list_recommendation_subscriptions` | List auto-apply recommendation subscriptions and their status (audit what auto-applies) |\n| `gads_set_recommendation_subscription` | Turn auto-apply recommendations ON/OFF (pause budget/bid recommendations that can silently raise spend) |\n\n#### Google Ads Authentication\n\nThe Google Ads tools use OAuth2 credentials. Provide them via environment variables or your ADC file:\n\n```bash\n# Option A: Explicit env vars\nexport GADS_CLIENT_ID=\"your-client-id\"\nexport GADS_CLIENT_SECRET=\"your-client-secret\"\nexport GADS_REFRESH_TOKEN=\"your-refresh-token\"\nexport GOOGLE_ADS_DEVELOPER_TOKEN=\"your-developer-token\"\nexport GOOGLE_ADS_CUSTOMER_ID=\"1234567890\"\n\n# Option B: Use Application Default Credentials (gcloud OAuth)\n# Run: gcloud auth application-default login\n# The server reads ~/.config/gcloud/application_default_credentials.json automatically\nexport GOOGLE_ADS_DEVELOPER_TOKEN=\"your-developer-token\"\nexport GOOGLE_ADS_CUSTOMER_ID=\"1234567890\"\n```\n\n> **Developer token:** Get yours at [Google Ads API Center](https://developers.google.com/google-ads/api/docs/first-call/dev-token). A test token works for sandbox accounts; a standard token is required for production.\n\n> **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.\n\n---\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `gtm_list_accounts` returns `[]` | Service account not added to GTM | Add service account email in GTM → Admin → User Management |\n| `Tag Manager API has not been used` error | API not enabled | Enable at console.cloud.google.com → APIs & Services → Tag Manager API |\n| `Permission denied` on tag update | Service account has Read-only | Upgrade to Publish permission in GTM User Management |\n| `gtm_list_tags` returns `[]` | Workspace is empty (no tags published) | Check a different workspaceId, or confirm tags exist in GTM dashboard |\n| 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 |\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/AINative-Studio/core\ncd packages/mcp-servers/ainative-gtm-mcp\nnpm install\nnpm run build\nnpm run dev\n```\n\n## License\n\nMIT — [AINative Studio](https://ainative.studio)\n",
  "bytes": 14201,
  "sha": "44ac65d09a65e89a1c4a7a6d4522329930b74bacfb536a6b0004afa62a1dcce7",
  "repo_slug": "ainative-studio/ainative-gtm-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ainative_studio_ainative_gtm_m_1712fa5e/readme"
}