Skip to main content
Glama
jarnielcataluna

gtm-tag-architect

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

  • /setup Interactive 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


Quickstart: How to Connect via MCP

Mode 1: Offline JSON Export (Zero API Setup)

  1. In GTM, go to Admin > Export Container and save as container.json.

  2. Configure your MCP client to point to the file via GTM_OFFLINE_CONTAINER_PATH.

Mode 2: Live Google Tag Manager API

  1. Enable Tag Manager API in Google Cloud Console.

  2. Create a Service Account, download the JSON key, and add the service account email in GTM Admin > User Management with Read or Edit permissions.

  3. 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.git

Antigravity 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

  1. Open Cursor Settings > Features > MCP Servers.

  2. Click + Add New MCP Server.

  3. 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:

/setup

The agent will interview you about:

  1. Site Type & Industry: E-Commerce, SaaS, Lead Gen, Content, Portfolio

  2. Framework: Next.js/React, WordPress, Laravel, Symfony, or Vanilla PHP

  3. Required Pixels: GA4, Meta, LinkedIn, Google Ads, PostHog

  4. 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-fixture

License

MIT

Available Tools

5 tools
gtm_add_tag_recipeB

Adds a pre-configured tag recipe (GA4 Core, Meta Pixel, PostHog, or LinkedIn) to the container workspace.

ParametersJSON Schema
NameRequiredDescriptionDefault
recipeYes
pixelIdNo
containerPathNo
measurementIdNo

TDQS

B3.2/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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_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.

ParametersJSON Schema
NameRequiredDescriptionDefault
containerPathNoOptional local path to container export JSON file

TDQS

A3.9/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
containerPathNoPath to container JSON file

TDQS

A3.5/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
industryYesTarget industry tracking taxonomy

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

  1. 5 tool updatesv0.1.0
    • First observedgtm_add_tag_recipe
    • First observedgtm_apply_consent_mode
    • First observedgtm_audit_container
    • First observedgtm_deduplicate_tags
    • First observedgtm_generate_datalayer_types

TDQS

A3.7/5.0

Scored across 5 tools

Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    A
    maintenance
    MCP server for Google Tag Manager and GA4, enabling tag management, consent auditing, workspace versioning, and analytics reporting through natural language.
    11
    67 npm
    2
    MIT
  • A
    license
    Not graded
    quality
    B
    maintenance
    MCP server for Google Tag Manager API v2, enabling programmatic management of accounts, containers, workspaces, tags, triggers, variables, and version workflows.
    18 npm
    14
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    An MCP server for the Google Tag Manager API v2 that enables AI assistants to query GTM accounts, containers, tags, triggers, variables, and unpublished changes.
    24
    2
    Apache 2.0