gtm-tag-architect
This MCP server lets you audit, fix, and enhance Google Tag Manager containers through a set of automated GTM tools.
Audit a GTM container — detects duplicate tags, missing triggers, unconsented pixels, and blocking scripts (local JSON or live API).
Deduplicate tags — removes duplicate GA4 and Meta Pixel tags and consolidates triggers.
Apply Consent Mode v2 — configures default consent state and enforces consent requirements on analytics/marketing tags.
Add tag recipes — quickly add pre-configured GA4, Meta Pixel, LinkedIn Insight, or PostHog tags with your IDs.
Generate dataLayer types — creates TypeScript definitions and helper push functions for E-commerce, SaaS, Lead Gen, or Content tracking.
Audits and manages Google Ads pixels within GTM, ensuring proper tagging and consent compliance.
Provides tools for managing Google Tag Manager containers, diagnosing tag/trigger defects, enforcing Consent Mode v2, and generating dataLayer contracts.
Audits and manages Meta (Facebook) pixels, deduplicates tags, and ensures Consent Mode v2 compliance.
Integrates PostHog tracking into GTM, providing diagnostic and remediation capabilities for PostHog tags.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gtm-tag-architectaudit my GTM container"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
gtm-tag-architect
A public, production-ready plugin for Google Antigravity, Claude Code, and Cursor that connects to Google Tag Manager via the Model Context Protocol (MCP).
It provides an interactive /setup command that interviews developers and marketers about their site, diagnoses container defects (duplicates, missing triggers, Consent Mode v2 violations), and generates optimized tracking taxonomies and dataLayer contracts for both TypeScript (Next.js/React) and PHP (WordPress/Laravel/Symfony).
Features
/setupInteractive Command: Guides you through a 3-stage interview and audit workflow.Deep Container Diagnostics: Audits duplicate GA4/Meta tags, orphaned triggers, unconsented marketing pixels, and render-blocking scripts.
Automated Remediation: Deduplicates tags and enforces Google Consent Mode v2 (or provides an explicit opt-out bypass for internal/US tools).
Multi-Framework dataLayer Contracts: Generates typed TypeScript definitions (
dataLayer.d.ts) or native PHP classes (GtmDataLayer.php) for WordPress, Laravel, Symfony, and custom backends.Industry Tracking Matrices: Pre-built taxonomy runbooks for E-Commerce, SaaS/PLG, B2B Lead Gen, and Technical Portfolios.
Dual-Mode MCP Server: Runs live against Google Tag Manager REST API v2 or audits local exported container JSON files offline (Zero API setup).
Related MCP server: mcp-gtm-ga4
Documentation & Guides
📖 Complete GTM MCP Setup & Credentials Guide: Detailed walkthrough for obtaining Google Cloud Service Account keys, GTM container permissions, GA4 Measurement IDs, Meta Pixels, LinkedIn Insight tags, and PostHog keys.
Quickstart: How to Connect via MCP
Mode 1: Offline JSON Export (Zero API Setup)
In GTM, go to Admin > Export Container and save as
container.json.Configure your MCP client to point to the file via
GTM_OFFLINE_CONTAINER_PATH.
Mode 2: Live Google Tag Manager API
Enable Tag Manager API in Google Cloud Console.
Create a Service Account, download the JSON key, and add the service account email in GTM Admin > User Management with Read or Edit permissions.
Set
GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json.
(See the Complete Setup Guide for step-by-step instructions with screenshots and permission configurations.)
MCP Client Configuration
For Google Antigravity
Clone or place this repository into your workspace or global customizations directory:
# In your project's .agents/plugins/ or ~/.gemini/config/plugins/
git clone https://github.com/jarnielcataluna/gtm-tag-architect.gitAntigravity will automatically discover the plugin, expose the /setup slash command, and register the MCP server defined in mcp_config.json.
For Claude Code / Claude Desktop
Register the server in your claude_desktop_config.json or project MCP settings:
{
"mcpServers": {
"gtm-tag-architect": {
"command": "node",
"args": ["/path/to/gtm-tag-architect/bin/gtm-mcp.js"],
"env": {
"GTM_OFFLINE_CONTAINER_PATH": "./fixtures/sample-ecommerce-container.json"
}
}
}
}For Cursor IDE
Open Cursor Settings > Features > MCP Servers.
Click + Add New MCP Server.
Name:
gtm-tag-architect| Type:command| Command:node /path/to/gtm-tag-architect/bin/gtm-mcp.js
Usage
Run the /setup Command
Inside Antigravity or Claude Code:
/setupThe agent will interview you about:
Site Type & Industry: E-Commerce, SaaS, Lead Gen, Content, Portfolio
Framework: Next.js/React, WordPress, Laravel, Symfony, or Vanilla PHP
Required Pixels: GA4, Meta, LinkedIn, Google Ads, PostHog
Privacy Strategy: Enforce Consent Mode v2 (Strict GDPR) vs. Opt-Out / Direct Firing
It then performs a diagnostic audit and presents you with an action menu to fix defects, apply consent rules, and export clean dataLayer contracts.
Testing & Local Audit
You can run the offline diagnostic test harness against the included test fixture:
npm install
npm run audit-fixtureLicense
MIT
Available Tools
5 toolsgtm_add_tag_recipeB
Adds a pre-configured tag recipe (GA4 Core, Meta Pixel, PostHog, or LinkedIn) to the container workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| recipe | Yes | ||
| pixelId | No | ||
| containerPath | No | ||
| measurementId | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the basic action ('adds... to the container workspace') but does not disclose whether the operation requires special permissions, what happens if the recipe or a matching tag already exists (idempotency/duplication risk), whether recipes create multiple underlying resources, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the operation and packs the recipe enumeration into a parenthetical. No filler or redundant phrasing; it earns its length though the parenthetical list is slightly dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no annotations, and no output schema, one sentence is insufficient. The description does not clarify which parameters apply to which recipes, how the container workspace is selected (given containerPath is optional), or what a successful result looks like. These are meaningful gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It adds value only for the 'recipe' parameter by humanizing the enum values. It leaves pixelId, containerPath, and measurementId unexplained, and the phrase 'pre-configured' actively creates confusion by implying no configuration is needed while three optional config parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource structure ('Adds a pre-configured tag recipe') and enumerates the exact recipe types (GA4 Core, Meta Pixel, PostHog, LinkedIn), making the tool's function immediately clear. The action of adding is clearly distinct from the sibling tools' operations (audit, deduplicate, apply consent mode, generate types).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the purpose statement: use this when you want to add a standard pre-configured tag rather than building one manually. However, there is no explicit when-to-use vs when-not-to-use guidance, no mention of alternatives (e.g., manual tag creation), and no note about which recipe fits which scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gtm_apply_consent_modeA
Configures Google Consent Mode v2 on all analytics and marketing tags (requiring ad_storage, ad_user_data, and analytics_storage).
| Name | Required | Description | Default |
|---|---|---|---|
| defaultState | No | Default consent state prior to user CMP interaction | |
| containerPath | No | Path to container JSON file |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations provided, so the description carries the full burden. The description states the tool 'Configures... on all analytics and marketing tags', which implies a broad mutation affecting many tags. However, it does not disclose any destructive behavior, reversibility, or side effects. It mentions specific requirements (ad_storage, ad_user_data, analytics_storage) which is useful, but it lacks details on what modifying these tags entails, such as whether it overwrites existing configurations. No contradiction with annotations since none exist, but transparency is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that clearly states purpose and includes necessary required storage types. It is front-loaded with the verb and object. No waste, every word serves a purpose. This is a model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description provides reasonable completeness for a configuration tool. It states what it does and which storage types are involved. However, it lacks details on what happens during configuration (e.g., whether it writes to the container, if it requires backup, the result of the operation). The tool has 2 parameters, both documented, so basic completeness is satisfied, but the behavioral implications of configuring all tags are not fully explained. The sibling tools have distinct purposes, so this tool's role is relatively clear, but more details on the configuration process would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds the context that these parameters are for configuring consent mode on tags. However, the description does not explain how the parameters interact (e.g., what happens if defaultState is denied versus granted). The parameter descriptions in the schema are basic ('Default consent state prior to user CMP interaction' and 'Path to container JSON file'). The description adds minimal extra meaning, just clarifying the overall purpose. Baseline 3 applies as schema covers parameters well, and description adds some value but not deep parameter behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool configures Google Consent Mode v2 with specific storage requirements (ad_storage, ad_user_data, analytics_storage). The verb 'Configures' and resource 'Google Consent Mode v2' are specific. While it could more explicitly distinguish from siblings (e.g., gtm_audit_container, gtm_deduplicate_tags), the purpose is clear enough to stand out from the list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (setting consent mode on tags) but does not explicitly state when to use this tool vs. alternatives like gtm_audit_container or gtm_add_tag_recipe. It lacks explicit 'when not to use' or alternative tools, but the context of configuring consent mode is a clear use case. The sibling tools have distinct purposes (auditing, deduplicating, adding recipes), so a clear distinction is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gtm_audit_containerA
Runs a deep diagnostic audit on a Google Tag Manager container. Identifies duplicate tags, missing triggers, unconsented tracking (Consent Mode v2), and heavy blocking scripts.
| Name | Required | Description | Default |
|---|---|---|---|
| containerPath | No | Optional local path to container export JSON file |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The term 'audit' implies a read-only operation, but the description does not explicitly state that no modifications are made. Since no annotations are provided, the description carries the burden, and while it suggests non-destructive behavior, it is not fully explicit about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise, consisting of two short sentences that efficiently convey the tool's purpose and key output categories. No unnecessary words or repetition are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists specific issues the audit identifies, giving context about what the tool returns. However, it does not specify the output format (e.g., report, list, JSON), which would enhance completeness given the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter containerPath is clearly described as 'Optional local path to container export JSON file', providing precise meaning about its type and purpose. This fully covers the schema, leaving no ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Runs') and resource ('Google Tag Manager container'), and lists concrete outputs (duplicate tags, missing triggers, unconsented tracking, heavy blocking scripts). This distinguishes it from sibling tools like gtm_deduplicate_tags or gtm_apply_consent_mode.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It only describes what the tool does, without stating scenarios where it is preferred over other GTM utilities, making it less helpful for usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gtm_deduplicate_tagsA
Deduplicates GA4 configuration and Meta Pixel tags in the GTM container, consolidating firing triggers and pruning duplicate base tags.
| Name | Required | Description | Default |
|---|---|---|---|
| containerPath | No | Path to container JSON file |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a mutating action ('pruning', 'deduplicating') but does not explicitly state that the container file is modified, whether the operation is reversible, or any side effects. The agent is not warned that this may be destructive or that the original file is overwritten. This is insufficient for a mutation tool without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence that front-loads the primary action and immediately states what it does. It contains no filler, repetition, or wasted words, making it highly concise and structured effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter with full schema coverage, no output schema, no annotations), the description is adequate but incomplete. It does not explain what the tool returns (if anything), nor does it mention whether it modifies the container file in place or how to handle potential side effects. Since no annotations exist, the description should cover these aspects more explicitly; it currently leaves the agent guessing about post-condition behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% description coverage for the only parameter, containerPath, with its description ('Path to container JSON file'). The tool description adds no additional meaning about the parameter. Since schema coverage is high, the baseline of 3 applies; the description offers no extra value on parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: deduplicating GA4 configuration and Meta Pixel tags in the GTM container. It specifies the action (deduplicate), the resource (GA4 and Meta Pixel tags in GTM container), and the method (consolidating firing triggers and pruning duplicate base tags). This clearly distinguishes it from siblings like gtm_audit_container (auditing) or gtm_add_tag_recipe (adding tags).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when dealing with duplicate tags, but it does not explicitly state when to use this tool versus alternatives or provide any exclusions. There is no mention of prerequisites (e.g., having a container file) or when not to use it. The purpose is clear, but the guidance on when to invoke it is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gtm_generate_datalayer_typesA
Generates production TypeScript type definitions and helper push functions for developers (E-commerce, SaaS, or Lead Gen).
| Name | Required | Description | Default |
|---|---|---|---|
| industry | Yes | Target industry tracking taxonomy |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states it generates types and helper functions, which is a clear action, but it does not disclose side effects (e.g., whether files are written to a repository, whether it affects existing code, or any authorization requirements). This is a moderate gap for a generation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence, front-loaded with the core function (generates production TypeScript type definitions and helper push functions) and adds target users and use cases. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter fully described in schema and no output schema, the description is adequate for a simple tool. However, it does not mention what the generated output looks like (though no output schema is needed), nor does it clarify the relationship to the 'content' industry enum value, which is listed in schema but not in the description. It is complete enough for basic use but could be enhanced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter 'industry' with an enum description 'Target industry tracking taxonomy'. The description adds context by listing example industries (E-commerce, SaaS, Lead Gen) within the main description, which clarifies the parameter options, but this is redundant with the enum. The description does not add significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates TypeScript type definitions and helper push functions, specifying the target use case (E-commerce, SaaS, or Lead Gen). The verb 'generate' and resource 'datalayer types' are specific, and it is distinct from sibling tools that perform auditing, deduplication, consent mode, and tag recipe actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (for developers, targeted at specific industries) but does not explicitly state when to use this tool vs alternatives. Sibling tools have different purposes, so a developer would infer usage, but there is no direct guidance on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
gtm_add_tag_recipe - First observed
gtm_apply_consent_mode - First observed
gtm_audit_container - First observed
gtm_deduplicate_tags - First observed
gtm_generate_datalayer_types
TDQS
Scored across 5 tools
Each tool targets a distinct action in the GTM workflow—audit, deduplicate, apply consent, add recipe, generate types—so an agent can usually pick the right one. Minor overlap exists where audit surfaces duplicates and consent gaps that deduplicate and apply_consent_mode then fix, but the strong action verbs keep the boundaries clear.
All tool names follow the identical `gtm_<verb>_<object>` snake_case pattern with perfect consistency. The `gtm_` prefix scopes everything to the domain, and every verb is a single lowercase action word.
Five tools is a well-scoped surface for a GTM tag-management assistant. Each tool addresses a distinct stage of the tag lifecycle—audit, cleanup, compliance, templating, and developer handoff—without feature bloat.
The core architecture workflow is well covered: audit, deduplicate, configure consent, add standard tags, and generate TypeScript datalayer helpers. Publication/preview submission and tag removal are missing, so agents may need workarounds, but the primary setup path is fully covered.
Maintenance
Related MCP Connectors
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
Google Ads MCP server — manage campaigns, keywords, and metrics.
MCP server for building and testing AI agents with multi-model experimentation and insights.
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP Server that provides a conversational interface to Google Tag Manager API, allowing users to manage tags, triggers, variables, and containers through natural language.-
- AlicenseAqualityAmaintenanceMCP server for Google Tag Manager and GA4, enabling tag management, consent auditing, workspace versioning, and analytics reporting through natural language.1167 npm2MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for Google Tag Manager API v2, enabling programmatic management of accounts, containers, workspaces, tags, triggers, variables, and version workflows.18 npm14MIT
- AlicenseAqualityBmaintenanceAn MCP server for the Google Tag Manager API v2 that enables AI assistants to query GTM accounts, containers, tags, triggers, variables, and unpublished changes.242Apache 2.0