Tag Pilot GTM

Tag Pilot GTM MCP

A free, read-only Model Context Protocol server for Google Tag Manager. Ask Claude, Cursor or any MCP client about your GTM containers: which tags fire on which triggers, how a variable is set up and what uses it, what publishing a workspace would change, the version history, and a Tag Pilot audit of the container.

No Google Cloud setup, no API key to copy. You don't need a GCP project, OAuth client, service account or gcloud. Add the server, ask a question, and approve once in your browser.

claude mcp add gtm -- npx -y @tagpilot/gtm-mcp

Get started

1. Install in your AI client (below). No configuration needed.
2. Ask something, e.g. "Audit my GTM container GTM-ABC1234" or "What changes in the Default Workspace aren't published yet?" The first time, a browser window opens (or your AI shows a link and a code like ABCD-1234):
   • sign in to your free Tag Pilot account, or create one;
   • check that the code matches and approve this computer;
   • sign in with the Google account that can see your Tag Manager containers and allow read-only Tag Manager access.
3. Ask again. You're connected; the computer shows up under Connected devices on the GTM MCP page.

Already use the Tag Pilot GA4 MCP or Search Console MCP? This is a separate server with its own connection (and its own Google consent), so you can install any of them.

Install

[Add to Cursor] [Install in VS Code]

Everything except the Claude Desktop extension runs the npm package with npx, so it needs Node.js 18 or newer. In the MCP Registry it's io.github.tagpilot/gtm-mcp.

Claude Desktop config file (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) and similar clients:

{  "mcpServers": {    "gtm": {      "command": "npx",      "args": ["-y", "@tagpilot/gtm-mcp"]    }  }}

Headless and CI: where nobody can approve in a browser, create a gtm:mcp key on the GTM MCP page and set TAGPILOT_API_KEY=tpk_… in the server's environment. The device connect is then skipped and only the Google sign-in link is shown.

How connecting works, and what Tag Pilot sees

The same flow as the GA4 MCP (RFC 8628-style device connect, like gh auth login): it works from any browser on any device, also over SSH, in containers or WSL, because nothing listens on your machine.

• Your Tag Manager data goes from your machine straight to Google (tagmanager.googleapis.com). It never passes through Tag Pilot.
• Tag Pilot only brokers the token exchange. It adds Tag Pilot's Google OAuth client credentials to Google's token endpoint and returns Google's answer. It stores no Google tokens and never logs them; it holds the one-time sign-in code for at most 10 minutes, and that code is useless without the PKCE verifier that stays on your machine.
• Read-only. The only Google scope requested is tagmanager.readonly. None of the tools can create, change, publish or delete anything, and the server only sends GET requests.
• Your credentials stay on your machine, in ~/.config/tagpilot/gtm-mcp/device.json (readable only by you).
• Disconnecting: revoke the device on the GTM MCP page, run npx -y @tagpilot/gtm-mcp logout, and remove the app's access at myaccount.google.com/permissions.

Tools

All tools are read-only. container_id is the numeric container ID from list_containers; the public ID (GTM-XXXXXXX) works too. Tools that read container contents read the live (published) version by default; pass workspace_id (from list_workspaces) for a workspace with its unpublished changes, or version_id (from list_versions) for an older version.

audit_container

Offline checks over one read of the container. They are rules of thumb, not GTM errors:

Rate limits and caching

The Tag Manager API allows only a few requests per second per user and has a daily quota, so the server is frugal:

• a container version (live or numbered) is one request; a workspace is one list request per entity kind (tags, triggers, variables, built-ins, templates, folders, plus clients and transformations for server containers), never one request per tag;
• get_tag, get_trigger, get_variable, find_references and audit_container reuse the same read, which is cached for a minute (numbered versions for 30 minutes);
• rate-limit errors (429, or 403 with a quota reason) and server errors are retried with backoff.

Workspace reads skip zones (Tag Manager 360); version reads include them.

Troubleshooting

"Not connected yet" (a link and a code like ABCD-1234): your AI shows them. Open the link in any browser (it doesn't have to be on this machine), sign in to Tag Pilot, check that the code matches, approve, and allow Tag Manager access, then tell your AI you're done: it retries your question (or calls connection_status). The server keeps checking in the background, so nothing needs restarting. The code is valid for 10 minutes; after that, ask again (or say "connect GTM") for a new one. To connect from a terminal instead (e.g. over SSH), run npx -y @tagpilot/gtm-mcp login: it shows the link, the code in a box and a countdown, and waits until you approve.

"The signed-in Google account has no access to …": use list_accounts and list_containers to see what it can read. To use another Google account, run npx -y @tagpilot/gtm-mcp logout and connect again.

"… has no live (published) version": the container was never published; pass workspace_id.

"This computer was disconnected from Tag Pilot": the device was revoked; ask again to reconnect. "Your Google sign-in expired or was revoked": ask again and approve again.

Rate limit or quota errors: wait a minute and ask again.

Check the setup: npx -y @tagpilot/gtm-mcp status. Logs go to stderr.

Configuration

Nothing is required. All variables are optional:

Commands: npx -y @tagpilot/gtm-mcp [serve|login|logout|status|--help|--version].

Development

See the repo README. GTM_MCP_TAGMANAGER_API_URL points the Google calls at a mock (used by npm run e2e).

License

Apache License 2.0. Copyright 2026 Tag Concierge sp. z o.o. The license does not cover the Tag Pilot name or logo (see NOTICE).