<div align="center">

**English** · [Español](README_es.md)

# Google Tag Manager MCP (`google-tag-manager-mcp`)

### The Forensic Auditing, Governance & Safe Staging Operating System for Google Tag Manager (Model Context Protocol).

**Stop flying blind with passive AI tools that hallucinate live changes. Audit, govern, stage, and defensively protect your Google Tag Manager containers and advertising attribution at an executive level.**

[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![Protocol](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-5c4ee5?style=flat-square)](https://modelcontextprotocol.io/)
[![Catalog](https://img.shields.io/badge/Tools-81%20Enterprise%20Tools-success?style=flat-square)](#the-81-tool-advertising--measurement-catalog)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square)](LICENSE)
[![Safety](https://img.shields.io/badge/Safety-Two--Phase%20Commit-brightgreen?style=flat-square)](#your-live-site-is-safe-two-phase-commit-security)

[Quick Start](#how-to-use-in-60-seconds-zero-coding) · [Two-Phase Safety](#your-live-site-is-safe-two-phase-commit-security) · [The 4 Attribution Killers](#the-four-silent-tracking-killers-destroying-your-roas) · [Tool Catalog](#the-81-tool-advertising--measurement-catalog) · [Dynamic Profiles](#context-window-optimization--dynamic-tool-profiles) · [Legal Notice](#legal-notice-trademark--disclaimer)

</div>

> [!IMPORTANT]
> **Guaranteed Production Safety & Performance:** Every mutation across tags, triggers, templates, or variables strictly adheres to **Two-Phase Commit** (edits occur inside an isolated staging workspace with an in-memory **Mutation-Aware Cache** reducing API calls by 80%). No AI agent can publish live containers or trigger breaking changes to production traffic without your explicit in-chat authorization (`confirmed=True`).

---

## How to Use in 60 Seconds (Zero Coding)

You don't need to write code or manage local development environments. If you use **Claude Desktop**, **Antigravity**, or **ChatGPT Desktop**, simply register the server configuration and copy the master prompt.

### Step 1: Connect the Server to your AI Client
Open your AI application's configuration file (e.g., `claude_desktop_config.json` for Claude Desktop) and add this block inside `"mcpServers"`:

```json
{
  "mcpServers": {
    "google-tag-manager": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/eddvasquez/google-tag-manager-mcp",
        "google-tag-manager-mcp"
      ],
      "env": {
        "GTM_ACCOUNT_ID": "your_gtm_account_id",
        "GTM_CONTAINER_ID": "your_gtm_container_id",
        "GTM_OAUTH_CLIENT_ID": "your_client_id",
        "GTM_OAUTH_CLIENT_SECRET": "your_client_secret",
        "GTM_OAUTH_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}
```

> [!TIP]
> **Local clone alternative:** If you cloned this repository locally, run `"command": "uv"` and `"args": ["--directory", "path/to/google-tag-manager-mcp", "run", "google-tag-manager-mcp"]`.

### Step 2: Copy & Paste this Master Prompt into your AI Chat

```text
Act as my World-Class Measurement Architect & Senior Google Tag Manager Consultant.

You have access to the 'google-tag-manager-mcp' server.

We operate strictly under enterprise measurement and high-performance advertising attribution standards:
1. NON-NEGOTIABLE RULE: Never publish live containers without staging changes in an isolated workspace and presenting the detailed diff for my explicit authorization (confirmed=True).
2. Begin by executing Phase 1: Forensic Ad Tracking Alignment Audit on my container (Account ID: [YOUR_ACCOUNT_ID], Container ID: [YOUR_CONTAINER_ID]).
3. Identify if any Conversion Linker tags are missing or paused, inspect Consent Mode v2 status across all marketing tags, and detect any duplicate conversion risks before proposing new tags.
```

---

## Your Live Site is Safe: Two-Phase Commit Security

The single biggest fear of a Media Buyer or Webmaster when connecting an AI to Google Tag Manager is: *What happens if the model hallucinates an invalid script, deletes an essential trigger, or breaks production tracking for thousands of visitors?*

This system incorporates **Mandatory Transactional Safeguards**:

1. **Isolated Workspace Staging:** When the AI prepares an action (creating a tag, tweaking triggers, adding Data Layer variables), mutations are executed inside a designated staging workspace. Live production traffic (`live`) is 100% untouched.
2. **Visual Diff & Integrity Report:** The AI inspects dependencies and presents the exact proposed diff in chat.
3. **Immutable Human Authorization Gate:** Only when you reply with explicit confirmation does the system execute version creation and live deployment (`confirmed=True`).
4. **Instant 1-Click Rollback:** In case of any unforeseen edge-case, the server provides an emergency rollback tool (`gtm_release_quick_rollback`) to restore the prior known-good version in seconds.

```mermaid
sequenceDiagram
    autonumber
    actor MB as Media Buyer / Engineer (User)
    participant IA as AI Coding Agent (Claude / Antigravity / ChatGPT)
    participant MCP as MCP Server (GTM Engine)
    participant GTM as Google Tag Manager API v2 (Live Site)

    MB->>IA: "Create a GA4 'generate_lead' event tag"
    Note over IA,MCP: PHASE 1: ISOLATED WORKSPACE STAGING (ZERO LIVE RISK)
    IA->>MCP: gtm_staging_prepare_ga4_event (Workspace: Staging)
    MCP->>GTM: Creates tag in isolated workspace (Draft)
    GTM-->>MCP: Staging confirmed (Live container untouched)
    MCP-->>IA: Returns StagingProposal (Diff + Audit summary)
    IA->>MB: Displays report: "Tag staged in Workspace #2. Ready to version & publish?"
    
    alt User Authorizes Deployment
        MB->>IA: "Looks great, publish it"
        IA->>MCP: gtm_release_publish_version (confirmed=True)
        MCP->>GTM: Freezes version & publishes to LIVE traffic
        GTM-->>MCP: Live deployment confirmed
        MCP-->>IA: ReleaseResult (Status: PUBLISHED)
        IA->>MB: "Version 7 published successfully to production."
    else User Rejects or Corrects
        MB->>IA: "Wait, change the trigger to form submission"
        IA->>MCP: gtm_staging_prepare_tag (Updates draft in staging workspace)
    end
```

---

## The Four Silent Tracking Killers Destroying your ROAS

1. **The Missing Conversion Linker (`gclidw`):** Without a Conversion Linker on All Pages, Safari ITP and iOS 14.5+ purge the Google Click Identifier (`gclid`), blinding Google Ads to downstream conversions and degrading Smart Bidding into random guessing.
2. **Consent Mode v2 Blindness:** Unconfigured tags (`NOT_SET`) in EEA or global compliant setups fail to transmit consent signals (`ad_user_data`, `ad_personalization`), preventing Google Ads from training audiences and optimizing bids.
3. **Transaction ID Omission (Algorithmic Poisoning):** Lead or Purchase conversion tags firing without a deduplication key (`orderId` / `lead_id`) trigger double-counting on page refreshes, artificially distorting CPA and burning ad budgets on phantom conversions.
4. **Custom HTML `document.write` DOM Crashes:** Legacy scripts invoking synchronous `document.write` get blocked by modern browsers or cause partial rendering freezes on mobile devices.

---

## The 81-Tool Advertising & Measurement Catalog

| Module | Tool Name | Description |
|---|---|---|
| **Discovery** | `gtm_discovery_list_accounts` | Lists all accessible Google Tag Manager accounts. |
| **Discovery** | `gtm_discovery_list_containers` | Lists containers under an account (Web, Server, Mobile). |
| **Discovery** | `gtm_discovery_get_container_snippet` | Retrieves official or generated `<script>` and `<noscript>` installation snippets. |
| **Discovery** | `gtm_discovery_list_workspaces` | Lists development branches and default workspaces. |
| **Discovery** | `gtm_discovery_list_tags` | Full inventory of tags with type, status, and triggers. |
| **Discovery** | `gtm_discovery_list_triggers` | Full inventory of triggers with filters and event conditions. |
| **Discovery** | `gtm_discovery_list_variables` | Lists all user-defined and Data Layer variables. |
| **Discovery** | `gtm_discovery_list_versions` | Historical version headers, changelogs, and authors. |
| **Discovery** | `gtm_discovery_list_user_permissions` | Lists all account-level and container-level user permissions and roles. |
| **Discovery** | `gtm_discovery_list_custom_templates` | Lists custom templates and Community Gallery templates in workspace. |
| **Discovery** | `gtm_discovery_list_zones` | Lists GTM 360 zones in workspace. |
| **Discovery** | `gtm_discovery_list_gtag_configs` | Lists Google Tag (gtag) centralized parameter configurations. |
| **Intelligence** | `gtm_audit_bot_and_click_fraud_risk` | Anti-Bot & Click Fraud Shield: Audits primary conversion tags for lack of honeypots or bot gating. |
| **Intelligence** | `gtm_audit_consent_geofencing_strategy` | Geofenced Consent Mode v2: Catches universal 'denied' blackouts on non-EEA traffic (US/LATAM). |
| **Intelligence** | `gtm_audit_conversion_value_hierarchy` | Value-Based Bidding (VBB) Hierarchy: Audits non-zero weighting for macro vs micro actions. |
| **Intelligence** | `gtm_audit_enhanced_conversions_normalization` | Enhanced Conversions Normalizer: Lints international E.164 phone formatting and lowercase email regex. |
| **Intelligence** | `gtm_audit_core_web_vitals_impact` | Core Web Vitals (LCP/INP) Analyzer: Flags render-blocking tags firing on All Pages instead of Window Loaded. |
| **Intelligence** | `gtm_audit_custom_template_sandbox_security` | Custom Template Sandbox Linter: Detects insecure HTTP endpoints and excessive sandboxed JS APIs. |
| **Intelligence** | `gtm_intelligence_reconcile_google_ads_contract` | Cross-MCP Bridge: Bi-directional reconciliation between Google Ads API conversions and GTM tags (interoperable with [`eddvasquez/google-ads-mcp`](https://github.com/eddvasquez/google-ads-mcp)). |
| **Intelligence** | `gtm_audit_user_permissions_governance` | Audits agency access, rogue account admins, and enforces least privilege. |
| **Intelligence** | `gtm_audit_360_zones_integrity` | Audits GTM 360 zones for type restriction whitelists and script security. |
| **Intelligence** | `gtm_audit_container_version_drift` | Measurement Drift Detector: Compares live active container against baseline to catch untracked changes. |
| **Intelligence** | `gtm_audit_event_id_cross_network_governance` | Cross-Network Deduplication Matrix: Verifies exact orderId/eventID parity across Google, Meta, and TikTok. |
| **Intelligence** | `gtm_intelligence_simulate_consent_recovery` | Simulates Consent Mode v2 AI modeled conversions volume and recovered revenue vs basic blackout. |
| **Intelligence** | `gtm_audit_smart_bidding_learning_risk` | Holding Period & Learning Phase Guard: Flags CPA volatility risks when modifying primary bidding tags. |
| **Intelligence** | `gtm_audit_bigquery_sgtm_schema_match` | Server-Side sGTM to BigQuery Schema Linter: Verifies event_timestamp, user_pseudo_id, and items arrays. |
| **Intelligence** | `gtm_intelligence_generate_tracking_scorecard` | Executive Attribution Health & ROAS Leakage Scorecard: 0-100 score with $ wasted spend model. |
| **Intelligence** | `gtm_audit_datalayer_schema_contract` | CI/CM DataLayer Linter: validates variables against GA4 Ecommerce, Lead Gen, and Cart-Data contracts. |
| **Intelligence** | `gtm_audit_form_attribution_match` | Audits hidden input injection & postMessage listeners for CRM attribution (HubSpot, Typeform, GHL). |
| **Intelligence** | `gtm_audit_url_passthrough_defense` | Verifies `enableUrlPassthrough` on Conversion Linker to stop attribution leaks across checkouts. |
| **Intelligence** | `gtm_audit_google_ads_action_mapping` | Cross-MCP Bridge: Reconcile Google Ads conversion actions against GTM 'awct' tags (interoperable with [`eddvasquez/google-ads-mcp`](https://github.com/eddvasquez/google-ads-mcp)). |
| **Intelligence** | `gtm_audit_cmp_integration_health` | Validates CMP Consent Initialization timing, defaults, and race conditions. |
| **Intelligence** | `gtm_intelligence_sgtm_cost_estimator` | Sizing & Cloud Run Cost Calculator for sGTM instances, egress, and GCP monthly bill. |
| **Intelligence** | `gtm_audit_ad_tracking_alignment` | Forensic audit of Conversion Linker, cross-domain, and Google Ads setup. |
| **Intelligence** | `gtm_audit_smart_bidding_poisoning` | Detects micro-triggers (scroll, timers, visibility) attached to primary Google Ads conversion tags. |
| **Intelligence** | `gtm_audit_enhanced_conversions_fidelity` | Audits Enhanced Conversions formatting (E.164 phone, sanitized email). |
| **Intelligence** | `gtm_audit_enhanced_conversions_leads_ec4l` | Audits real-time contact data capture on form submits for offline matching. |
| **Intelligence** | `gtm_audit_conversion_value_currency` | Validates dynamic conversion values and ISO-4217 currencies for tROAS. |
| **Intelligence** | `gtm_audit_value_based_bidding_readiness` | Evaluates net margin tracking and tiered lead valuations for Value-Based Bidding. |
| **Intelligence** | `gtm_audit_consent_mode_v2` | Audits tag consent settings (`ad_storage`, `ad_user_data`, etc.). |
| **Intelligence** | `gtm_audit_consent_mode_advanced_modeling` | Classifies Basic vs Advanced Consent Mode and estimates AI signal recovery. |
| **Intelligence** | `gtm_audit_itp_cookie_defense` | Audits Safari ITP defenses, first-party cookie longevity, and iOS click IDs. |
| **Intelligence** | `gtm_audit_multichannel_tag_collision` | Detects tag collisions and missing `event_id` deduplication across Google, Meta, and TikTok. |
| **Intelligence** | `gtm_audit_google_ads_conversion_integrity` | Inspects transaction IDs, deduplication keys, and Enhanced Conversions. |
| **Intelligence** | `gtm_audit_ga4_measurement_alignment` | Validates Measurement IDs and canonical `snake_case` event naming. |
| **Intelligence** | `gtm_audit_datalayer_integrity` | Cross-validates Custom Event triggers against DataLayer variables. |
| **Intelligence** | `gtm_audit_container_bloat_and_hygiene` | Detects orphaned triggers, orphaned variables, and legacy paused tags. |
| **Intelligence** | `gtm_audit_custom_html_security` | Scans Custom HTML for `document.write`, insecure HTTP, and CSP issues. |
| **Intelligence** | `gtm_audit_server_container_readiness` | Audits Server Containers (sGTM), client templates, and FPID preservation. |
| **Intelligence** | `gtm_audit_sgtm_transformations_and_clients` | Inspects sGTM transformations for PII anonymization and client proxy setups. |
| **Staging** | `gtm_staging_scaffold_anti_bot_shield` | Scaffolds Honeypot variables & Turnstile blocking triggers on primary conversion tags. |
| **Staging** | `gtm_staging_scaffold_consent_geofence` | Scaffolds Geo-Fenced Consent Mode v2 (EEA 'denied' vs non-EEA 'granted'). |
| **Staging** | `gtm_staging_scaffold_oct_attribution_vault` | Scaffolds 90-day 1st-party cookie & localStorage Attribution Vault for offline CRM imports. |
| **Staging** | `gtm_staging_generate_sgtm_terraform_iac` | Generates validated Terraform HCL for sGTM Cloud Run provisioning with custom domains. |
| **Staging** | `gtm_staging_import_gallery_template` | Official Community Template Gallery Importer: 1-click import with explicit permission acknowledgement. |
| **Staging** | `gtm_staging_scaffold_vbb_customer_acquisition_tag` | 1-Click New Customer Acquisition (NCA) & pLTV Scaffolding: purchase tag with NCA multipliers. |
| **Staging** | `gtm_staging_import_container_json` | CI/CD Container Importer: staged merge of canonical GTM JSON blueprints with conflict resolution. |
| **Staging** | `gtm_staging_scaffold_cart_data_tag` | 1-Click Cart-Data Scaffolding: purchase tag with product items and line margins for tROAS profit bidding. |
| **Staging** | `gtm_staging_simulate_sgtm_pipeline` | Server-Side sGTM simulation: validates HTTP client parsing, PII redactions, and outbound dispatch. |
| **Staging** | `gtm_staging_simulate_event_firing` | In-memory tag/trigger simulation without browser: inspects fired tags and extracts ad payloads. |
| **Staging** | `gtm_staging_scaffold_lead_desanonymization_pack` | 1-Click Media Buyer Pack: Persist gclid/wbraid, inject hidden inputs, and decorate WhatsApp links. |
| **Staging** | `gtm_staging_scaffold_google_ads_conversion` | 1-Click complete Google Ads conversion triad (DLV, Trigger, Tag, Deduplication). |
| **Staging** | `gtm_staging_prepare_tag` | Drafts or updates a tag in an isolated workspace. |
| **Staging** | `gtm_staging_prepare_trigger` | Drafts or updates a trigger with logic filters in workspace. |
| **Staging** | `gtm_staging_prepare_variable` | Drafts or updates Data Layer variables in workspace. |
| **Staging** | `gtm_staging_prepare_conversion_linker` | 1-click scaffolding of an enterprise Conversion Linker tag. |
| **Staging** | `gtm_staging_prepare_consent_mode_defaults` | Scaffolds Consent Mode v2 default tag on Consent Initialization. |
| **Staging** | `gtm_staging_prepare_ga4_event` | Scaffolds standard GA4 recommended events with consent defaults. |
| **Staging** | `gtm_staging_enable_built_in_variables_batch` | Batch enables essential ad tracking variables (pageUrl, clickId, formId). |
| **Staging** | `gtm_staging_organize_folders` | Automatically structures enterprise folders (Core, Ads, GA4, Meta, Utility). |
| **Staging** | `gtm_staging_quick_preview` | Generates Tag Assistant preview environment without publishing. |
| **Staging** | `gtm_staging_sync_workspace` | Synchronizes staging workspace with latest container version, detecting conflicts. |
| **Staging** | `gtm_staging_inspect_workspace_diff` | Computes unversioned entity diff against the live container. |
| **Staging** | `gtm_staging_export_workspace_json` | Exports entire staging workspace as a portable canonical GTM JSON blueprint. |
| **Staging** | `gtm_staging_create_workspace` | Creates an isolated ephemeral staging workspace. |
| **Staging** | `gtm_staging_delete_workspace` | Deletes a staging workspace after testing. |
| **Release** | `gtm_release_create_version` | Freezes workspace into an immutable release version. |
| **Release** | `gtm_release_publish_version` | Protected live deployment (blocks without `confirmed=True`). |
| **Release** | `gtm_release_quick_rollback` | Instant emergency rollback to previous known-good version. |
| **Release** | `gtm_release_list_environments` | Lists environments configured for container (Live, QA, Dev). |
| **Release** | `gtm_release_get_live_version` | Retrieves metadata of currently active version in production. |

---

## Context Window Optimization & Dynamic Tool Profiles

To keep AI context windows lean and token-efficient across Claude Desktop or ChatGPT, `google-tag-manager-mcp` supports dynamic profiles via the `GTM_MCP_PROFILE` environment variable or `tools_config.yaml`:

| Profile | Active Tools | Use Case |
|---|---|---|
| `all` (default) | 81 Tools + 2 Resources | Full enterprise operations (audit, staging, release). |
| `audit_only` | 46 Tools | Forensic audits, Scorecard, and Smart Bidding intelligence without mutations. |
| `media_buyer` | 76 Tools | Complete audits, Scorecard, simulation, and 1-click scaffolding without live production release tools. |
| `developer` | 44 Tools | Discovery, manual staging, container import, template management, IaC, and release management. |
| `minimal` | 12 Tools | Read-only discovery and inventory lookup. |



Configure in your client settings:
```json
"env": {
  "GTM_MCP_PROFILE": "media_buyer"
}
```


---

## Legal Notice, Trademark & Disclaimer

- **Google Tag Manager, Google Ads, Google Analytics, and GA4** are registered trademarks of Google LLC.
- This software is an independent open-source Model Context Protocol server developed to provide programmatic interoperability with Google Tag Manager API v2.
- It is not officially endorsed, affiliated with, or sponsored by Google LLC.
- **Safety Guarantee:** Users retain full control over live publications through the mandatory Two-Phase Safety confirmation protocol.

---

## License

This project is licensed under the **Apache License 2.0**. See the [LICENSE](LICENSE) file for details.