gtm-mcp

MCP server for full Google Tag Manager management via the GTM API v2: tags, triggers, variables and versions.

Tools (22)

Hierarchy: Account → Container → Workspace → (Tags / Triggers / Variables)

Related MCP server: Google Tag Manager MCP Server

Typical flow

1. get_accounts()                                    → account_id
2. get_containers(account_id)                        → container_id
3. get_workspaces(account_id, container_id)          → workspace_id
4. get_workspace_status(...)                          → review pending changes
5. [create/edit tags, triggers, variables]
6. create_version(account_id, container_id, workspace_id, name="v1")
7. publish_version(account_id, container_id, version_id)

Setup

1. Create a Google Cloud project (or reuse one) and enable the Tag Manager API.

2. Create an OAuth 2.0 Client ID of type "Desktop app" and download it as client_secret.json.

3. If the app is in "Testing" mode, add your Google account as a test user.

4. Install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

5. Run the OAuth flow once:

   CLIENT_SECRET_PATH=~/.config/gtm-mcp/client_secret.json python3 setup_auth.py

   This opens a browser — log in and grant access. Credentials are saved to ~/.config/gtm-mcp/credentials.json.

⚠️ Only enable this MCP when you're actually working on GTM — leaving it always-on in a client that doesn't cache the OAuth session can trigger the auth flow on every startup.

MCP client configuration

{
  "mcpServers": {
    "gtm": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["/path/to/gtm-mcp/server.py"]
    }
  }
}

Confirmation required for critical operations

These tools require confirmed=True. Called without it, they return a JSON with requires_confirmation: true that the calling agent MUST show to the user and wait for a response before repeating the call with confirmed=True.

# 1. First call — no confirmed
publish_version(account_id="123456789", container_id="7654321", version_id="12")
# → returns requires_confirmation: true → show it to the user

# 2. Second call — after the user confirms
publish_version(account_id="123456789", container_id="7654321", version_id="12", confirmed=True)

Response size

List/get tools strip fields the GTM API always includes but no workflow ever uses (path, fingerprint, monitoringMetadata, tagManagerUrl, features), and parent IDs already known from the call's own parameters. Measured against real data: 39-81% smaller responses depending on the tool. create_version/publish_version return a summary instead of the full nested container snapshot (every tag/trigger/variable embedded) that the underlying API sends back.

Security

• Every tool carries MCP Tool Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) describing its effect up front.

• Execution errors propagate as real MCP protocol errors (isError=true), never as a JSON payload that looks successful with an error key buried inside it.

Notes

• All changes (create/edit/delete) stay in the workspace until published with create_version + publish_version.

• update_tag/update_trigger/update_variable do a GET before the PUT to preserve unspecified fields — you won't lose parameters by omission. Verified live with a full create → edit → delete round trip on each.

• ⚠️ revert_tag on a tag that was never published deletes it rather than restoring a prior state — "revert" means "go back to the last published version," and if the tag never existed in a published version, that version is "doesn't exist." Verified live; this is documented API behavior, not a bug in this server.

• Common tag_type values: googtag (GA4/Google Tag), html (custom HTML), gclidw (Ads conversion), ua (legacy Universal Analytics).

• Common trigger_type values: pageview, customEvent, linkClick, formSubmission, domReady.

• Common variable_type values: v (Data Layer), k (Cookie), u (URL), jsm (Custom JS).

• parameters is a list of {type, key, value} where type is one of template, boolean, integer, list or map.

License

MIT — see LICENSE.