google-tag-manager-mcp
This server lets MCP-compatible AI clients (like Claude) read and manage Google Tag Manager accounts through natural language, with both local and remote OAuth2-based deployment options.
Manage GTM accounts: list, get, update account details.
Manage containers: create, list, get, update, remove, combine, lookup by destination, move tag IDs, and fetch install snippets.
Manage workspaces: full CRUD plus create version, get status, sync, quick preview, and resolve conflicts.
Manage tags, triggers, variables, built-in variables, folders, clients, zones, templates, transformations, and gtag configs: create, read, update, list, remove, revert (where supported), plus folder entity operations and template gallery imports.
Manage destinations and environments: list/get/link destinations; CRUD environments and reauthorize them.
Manage versions and version headers: get, live, publish, set latest, undelete, update, remove, list, latest.
Manage user permissions: create, get, list, update, remove account user permissions.
Safety guardrails: destructive actions (publish, remove, revert, sync, link, etc.) require
confirm=True.Flexible auth modes: local STDIO for single-user desktop use; remote HTTP server with OAuth 2.1 for Claude Teams, claude.ai, and multi-user setups.
Provides tools for managing Google Tag Manager accounts, containers, tags, triggers, variables, workspaces, versions, environments, folders, clients, zones, templates, transformations, and user permissions via the GTM API.
Google Tag Manager MCP
A Python Model Context Protocol (MCP) server for the Google Tag Manager API v2. Connect Claude (or any MCP-compatible AI client) directly to your GTM accounts to manage tags, triggers, variables, workspaces, versions, environments, and more — all in natural language.
The server is also an OAuth 2.1 authorization server, so it works as a remote connector anywhere Claude supports custom MCP servers — claude.ai (personal), Claude Desktop, and Claude Teams. For Teams, the org owner adds the URL once and each member authenticates individually on first use.
Tools (18 consolidated per-resource tools)
Each tool takes an action parameter that selects the operation, plus resource addressing (parent / path) and optional config, params, and confirm fields. Destructive actions require confirm=True.
Tool | Actions |
| get, list, update |
| create, get, list, update, remove + combine, lookup, move_tag_id, snippet |
| create, get, list, update, remove + create_version, get_status, sync, quick_preview, resolve_conflict |
| create, get, list, update, remove, revert |
| create, get, list, update, remove, revert |
| create, get, list, update, remove, revert |
| create, list, remove, revert |
| create, get, list, update, remove + revert, entities, move_entities_to_folder |
| create, get, list, update, remove, revert |
| create, get, list, update, remove, revert |
| create, get, list, update, remove + revert, import_from_gallery |
| create, get, list, update, remove, revert |
| create, get, list, update, remove |
| get, list, link |
| create, get, list, update, remove + reauthorize |
| get, live, publish, set_latest, undelete, update, remove |
| list, latest |
| create, get, list, update, remove |
Consolidated tool design
Each tool takes a uniform set of parameters:
action— the operation to perform (e.g."list","create","publish")parent— resource path of the parent (e.g."accounts/123/containers/456/workspaces/7") — used for create and listpath— full resource path of the entity — used for get, update, remove, and other single-resource operationsconfig— dict of fields for create / update bodyparams— dict of extra query parametersconfirm— boolean, requiredTruefor destructive actions
Example — list tags in a workspace:
gtm_tag(action="list", parent="accounts/123/containers/456/workspaces/7")Example — publish a version (destructive, requires confirmation):
gtm_version(action="publish", path="accounts/123/containers/456/versions/9", confirm=True)Confirmation guardrail
The following actions are considered destructive and require confirm=True. Without it, the tool immediately returns a structured message asking you to re-call with confirm=True:
publish, remove, revert, undelete, combine, move_tag_id, move_entities_to_folder, sync, create_version, resolve_conflict, reauthorize, link
This prevents accidental mutations from ambiguous prompts.
Related MCP server: unboundai-gtm-mcp-server
How auth works
There are two modes. Pick one.
Mode A — Local STDIO (one user, no server)
Use this if you only want it on your own machine. setup_local_auth.py runs the Google OAuth flow once and stores your token in ~/.config/gtm-mcp/token.json. Claude Desktop launches server.py as a subprocess. No Firestore, no Cloud Run, no public URL.
Mode B — Remote HTTP server (Claude Teams, claude.ai, multi-user)
The MCP server is also an OAuth 2.1 authorization server. When Claude connects:
Claude discovers our metadata at
/.well-known/oauth-protected-resourceand/.well-known/oauth-authorization-server.Claude registers itself via Dynamic Client Registration (
POST /oauth/register).Claude redirects the user to
/oauth/authorize. We delegate identification to Google OAuth.After Google login, we issue our own opaque bearer token to Claude — Google credentials never leave the server.
On each
/mcprequest Claude sends our bearer; we map it server-side to the right user's stored Google credentials and call the GTM APIs.
Prerequisites
Python 3.10+
A Google Tag Manager account you have access to
A Google Cloud project
Step 1 — Set up Google Cloud
1a. Create a project and enable the Tag Manager API
Go to the Google Cloud Console.
Create or select a project.
APIs & Services → Library, enable Tag Manager API.
1b. Create OAuth 2.0 credentials
APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID.
Application type: Web application.
Add Authorized redirect URIs:
http://localhost:8080/auth/callback(local dev / setup_local_auth.py)https://YOUR-CLOUD-RUN-URL/auth/callback(remote deployment — add after deploy)
Click Create, then Download JSON → save as
client_secret.jsonin the project root (gitignored). You can also copy the Client ID / Client Secret straight into env vars.
1c. OAuth consent screen
APIs & Services → OAuth consent screen.
Choose Internal for a Google Workspace org (recommended for teams), or External for personal/individual use.
Add scopes:
https://www.googleapis.com/auth/tagmanager.readonlyhttps://www.googleapis.com/auth/tagmanager.edit.containershttps://www.googleapis.com/auth/tagmanager.delete.containershttps://www.googleapis.com/auth/tagmanager.edit.containerversionshttps://www.googleapis.com/auth/tagmanager.publishhttps://www.googleapis.com/auth/tagmanager.manage.users
If using External in Testing mode, add each user's email under Test users.
1d. Enable Firestore (Mode B only)
The server stores OAuth bearer tokens and per-user Google credentials in Firestore (collection user_tokens_gtm).
In Cloud Console, Firestore → Create database → Native mode, pick a region.
Grant the Cloud Run service account Cloud Datastore User role under IAM & Admin → IAM.
Step 2 — Install
git clone https://github.com/dhawalshah/gtm-mcp
cd gtm-mcp
pip install -r requirements.txt
cp .env.example .env # fill in valuesStep 3 — Mode A: Local STDIO
python setup_local_auth.pyA browser opens, you sign in with Google, the script writes ~/.config/gtm-mcp/token.json.
Then add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"google-tag-manager": {
"command": "python",
"args": ["/absolute/path/to/gtm-mcp/server.py"],
"env": {
"OAUTH_CONFIG_PATH": "/absolute/path/to/client_secret.json",
"MCP_USER_EMAIL": "you@yourcompany.com"
}
}
}
}Restart Claude Desktop. You're done — skip the rest.
Step 3 — Mode B: Remote HTTP server (Claude Teams / claude.ai)
Deploy to Cloud Run
gcloud run deploy gtm-mcp \
--source . \
--region YOUR_REGION \
--project YOUR_PROJECT_ID \
--platform managed \
--port 8080 \
--allow-unauthenticated \
--set-env-vars "GCP_PROJECT_ID=your-project-id,BASE_URL=https://YOUR-SERVICE-URL.run.app,OAUTHLIB_RELAX_TOKEN_SCOPE=1,ALLOWED_DOMAINS=yourcompany.com" \
--set-secrets "OAUTH_CONFIG_PATH=gtm-mcp-client-secret:latest"Required: OAUTHLIB_RELAX_TOKEN_SCOPE=1 — Google's OAuth response often returns a superset of the requested scopes; without this env var, google-auth-oauthlib raises "Scope has changed" in /auth/callback and the entire auth flow fails.
Recommended: load client_secret.json from Secret Manager rather than baking it into the image or passing the raw secret as a plain env var. Store the file as a secret, then mount it at runtime via --set-secrets.
After it's up, go back to APIs & Services → Credentials → your OAuth client and add the live callback URL:
https://YOUR-SERVICE-URL.run.app/auth/callbackConnect from Claude
Claude Teams (org owner adds it once for everyone):
Settings → Connectors → Add custom connector
URL:
https://YOUR-SERVICE-URL.run.app/mcpEach member clicks Connect, signs in with Google, done.
claude.ai personal:
Settings → Connectors → Add custom connector
URL:
https://YOUR-SERVICE-URL.run.app/mcp
Claude Desktop with a remote server:
{
"mcpServers": {
"google-tag-manager": {
"url": "https://YOUR-SERVICE-URL.run.app/mcp"
}
}
}Environment Variables
Variable | Required | Description |
| Mode B | Public URL of this service. Used for OAuth metadata and as the canonical resource URI tokens are bound to. |
| Mode B | GCP project hosting Firestore. |
| Both† | Path to |
| Mode B† | Google OAuth client ID (alternative to |
| Mode B† | Google OAuth client secret (alternative to |
| Mode B | Set to |
| Mode A | Your email — set in Claude Desktop config so the server finds your stored token. |
| No | Comma-separated email domain allowlist (e.g. |
| No | HTTP port (default |
| No | Python log level (default |
† Set either OAUTH_CONFIG_PATH or GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET.
Quota
The GTM API v2 has a low default quota: approximately 0.25 QPS, 15 requests/minute, and 10,000 requests/day per GCP project. Unlike Google Ads or Analytics, the quota does not auto-upgrade with billing.
If you hit quota errors, raise limits via Cloud Console → APIs & Services → Tag Manager API → Quotas & System Limits.
The client has built-in rate throttling and exponential backoff to stay within default limits during normal use.
OAuth endpoint reference (Mode B)
Endpoint | Spec | Purpose |
| RFC 9728 | Advertises the canonical resource URI and authorization server. |
| RFC 8414 | Authorization server metadata. |
| RFC 7591 | Dynamic Client Registration. |
| OAuth 2.1 | Starts the auth code flow with PKCE; redirects to Google. |
| — | Google redirects here; we mint our authorization code and bounce back to the MCP client. |
| OAuth 2.1 | Authorization code + refresh token grants. |
A GET /mcp without a valid bearer returns 401 with a WWW-Authenticate: Bearer resource_metadata="…" header pointing at the protected-resource metadata document, which is how a standards-compliant MCP client discovers the rest.
Reference
The reference/ folder holds the upstream stape-io/gtm-mcp TypeScript server, cloned as an API-shape reference during development. It is listed in .gitignore and excluded from Docker/Cloud Run builds — it is not part of the deployable app.
Tech Stack
FastMCP — MCP server framework
FastAPI + uvicorn — HTTP wrapper
Google Auth / google-api-python-client — Google OAuth and API access
Firestore — Per-user token storage and OAuth-server state (Mode B)
Google Cloud Run — Serverless hosting
About Dhawal Shah
I run a 40-plus person digital marketing agency out of Singapore, and I build the automation my own teams use. This server is one of those tools rather than a weekend project: it runs against live Tag Manager accounts every week, which is why the read-only surface is wide and the write surface is deliberately narrow.
Fourteen years building companies across Asia behind it. 5,000+ campaigns, 400+ brands, 30+ startups advised, and 300+ training sessions for teams including Sony, Toyota, DHL and Interpol. I am also an Accredited Director with the Singapore Institute of Directors, which in practice means I get asked what breaks, who is accountable and what it costs before anyone asks what it can do.
I write up the routines and agents I actually run at dhawalshah.net.
Worth reading alongside this repo: Claude Code for Marketing: Every Channel from One Terminal.
License
MIT
Available Tools
18 toolsgtm_accountGtm AccountB
Manage GTM accounts.
Actions:
list: list all accessible accounts (no parent needed).
get: get one account. path="accounts/{accountId}".
update: update an account. path="accounts/{accountId}", config={...}.
Inputs: action (required), path, config, params, +1 more. Returns: object
gtm_built_in_variableGtm Built In VariableB
Manage GTM built-in variables.
Actions:
list: parent=.
create: parent=, params={"type": ""}.
remove: path="/built_in_variables", params={"type": "..."}, confirm=true.
revert: path="/built_in_variables", params={"type": "..."}, confirm=true.
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_clientGtm ClientB
Manage GTM clients within a workspace. Same action set as gtm_tag (create, get, list, update, remove, revert; remove/revert require confirm=true).
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_containerGtm ContainerA
Manage GTM containers.
Standard CRUD (list/create: parent='accounts/{a}'; get/update/remove: path='accounts/{a}/containers/{c}') plus:
combine: path=, params={containerId,...}, confirm=true. (destructive)
lookup: params={destinationId} -> find container by destination. (read-only; no parent/path needed)
move_tag_id: path=, params={...}, confirm=true. (destructive)
snippet: path= -> GTM install snippet. (read-only)
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_destinationGtm DestinationA
Manage GTM destinations.
Actions:
list: parent=''.
get: path='/destinations/{id}'.
link: parent='', params={destinationId}, confirm=true. (Note: Google has deprecated destination linking via API.) (destructive)
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_environmentGtm EnvironmentB
Manage GTM environments. Standard CRUD (list/create: parent=''; get/update/remove: path='/environments/{id}') plus:
reauthorize: path='/environments/{id}', confirm=true. (destructive)
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_folderGtm FolderB
Manage GTM folders.
Standard CRUD+revert like gtm_tag, plus:
entities: path="/folders/{id}" → list entities in folder. (read-only)
move_entities_to_folder: path="/folders/{id}", params={tagId/triggerId/variableId}, confirm=true. Moves entities into the folder. (destructive)
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_gtag_configGtm Gtag ConfigC
Manage GTM Google tag (gtag) config. Standard CRUD (no revert).
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_tagGtm TagB
Manage GTM tags within a workspace.
Actions:
list: parent="accounts/{a}/containers/{c}/workspaces/{w}".
get: path="/tags/{tagId}".
create: parent=, config={tag definition}.
update: path="/tags/{tagId}", config={...}.
remove: path="/tags/{tagId}", confirm=true. (destructive)
revert: path="/tags/{tagId}", confirm=true. (destructive)
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_templateGtm TemplateC
Manage GTM custom templates. Standard CRUD+revert plus:
import_from_gallery: parent= (or path="/templates"), confirm=true. Imports a Community Template Gallery template.
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_transformationGtm TransformationB
Manage GTM transformations within a workspace. Same action set as gtm_tag (create, get, list, update, remove, revert; remove/revert require confirm=true).
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_triggerGtm TriggerB
Manage GTM triggers within a workspace. Same action set as gtm_tag (create, get, list, update, remove, revert; remove/revert require confirm=true).
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_user_permissionGtm User PermissionB
Manage GTM account user permissions.
Actions:
list: parent='accounts/{id}'.
get: path='accounts/{id}/user_permissions/{permId}'.
create: parent='accounts/{id}', config={emailAddress, accountAccess, containerAccess}.
update: path='accounts/{id}/user_permissions/{permId}', config={...}.
remove: path='accounts/{id}/user_permissions/{permId}', confirm=true. (destructive)
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_variableGtm VariableA
Manage GTM variables within a workspace. Same action set as gtm_tag (create, get, list, update, remove, revert; remove/revert require confirm=true).
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_versionGtm VersionA
Manage GTM container versions.
Actions:
get: path='/versions/{id}'.
live: path='' (or parent='') -> currently-published version. (read-only)
publish: path='/versions/{id}', confirm=true. PUSHES LIVE. (destructive)
set_latest: path='/versions/{id}', confirm=true. (destructive)
undelete: path='/versions/{id}', confirm=true. (destructive)
update: path='/versions/{id}', config={...}.
remove: path='/versions/{id}', confirm=true. (destructive)
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_version_headerGtm Version HeaderB
List GTM container version headers.
Actions:
list: parent=''.
latest: parent='' -> latest version header. (read-only)
Inputs: action (required), path, params, parent. Returns: object
gtm_workspaceGtm WorkspaceA
Manage GTM workspaces.
Standard CRUD (list/create: parent=; get/update/remove: path=) plus:
create_version: path=, config={name,notes}, confirm=true. (destructive)
get_status: path= -> uncommitted changes. (read-only)
sync: path=, confirm=true. (destructive)
quick_preview: path= -> preview of unsubmitted changes. (read-only)
resolve_conflict: path=, config={...}, confirm=true. (destructive)
Inputs: action (required), path, config, params, +2 more. Returns: object
gtm_zoneGtm ZoneB
Manage GTM zones within a workspace. Same action set as gtm_tag (create, get, list, update, remove, revert; remove/revert require confirm=true).
Inputs: action (required), path, config, params, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool is explicitly scoped to a distinct GTM entity (account, container, workspace, tag, trigger, etc.), with names like gtm_tag and gtm_trigger making the target resource clear. Despite shared CRUD actions, the entity distinction eliminates any ambiguity.
All tools follow the consistent pattern gtm_<entity> in snake_case, and actions within each tool use standard verbs (list, get, create, update, remove, revert). This uniform naming convention makes the tool set predictable and easy to navigate.
At 18 tools, the count is on the higher end of the typical range, but it is justified by the breadth of GTM's API which includes many distinct entity types. Each tool earns its place by covering a unique resource, so the count feels appropriate for the domain's complexity.
The server covers all major GTM entities including accounts, containers, workspaces, tags, triggers, variables, folders, clients, zones, templates, transformations, destinations, environments, versions, and user permissions. It also includes built-in variables and version headers, providing comprehensive lifecycle management with no obvious gaps.
Related MCP Connectors
Hosted Google Tag Manager MCP server, with each action switched on or off per account.
Hosted Google Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Google Ads MCP server — manage campaigns, keywords, and metrics.
Hosted BigQuery MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
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.-
- AlicenseAqualityDmaintenanceMCP server for Google Tag Manager API, enabling users to manage containers, tags, and triggers through natural language using Google Application Default Credentials.1894 npmApache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP server for Google Tag Manager API v2, enabling programmatic management of accounts, containers, workspaces, tags, triggers, variables, and version workflows.46 npm15MIT
- FlicenseNot gradedqualityBmaintenanceA remote MCP server for Google Tag Manager that enables AI assistants to manage GTM accounts, containers, tags, triggers, variables, and more via OAuth or service account authentication.1-