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)

Tool	What it does
get_accounts	List accessible GTM accounts — entry point
get_containers	Containers in an account
get_workspaces	Workspaces in a container (usually "Default Workspace")
get_workspace_status	Pending changes vs. the published version
get_tags / get_tag	List or detail tags
create_tag / update_tag / delete_tag / revert_tag	Tag CRUD
get_triggers / get_trigger	List or detail triggers
create_trigger / update_trigger / delete_trigger	Trigger CRUD
get_variables	List variables
create_variable / update_variable / delete_variable	Variable CRUD
get_versions	History of published versions
create_version	Snapshot the current workspace (restore point)
publish_version	Publish a version to production

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"]
    }
  }
}

Env var	Default	Purpose
GOOGLE_GTM_CREDENTIALS	~/.config/gtm-mcp/credentials.json	Path to the credentials file generated by setup_auth.py

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