MCP Server for Google Tag Manager

An interface to the Google Tag Manager API over MCP, in two flavours: a hosted server with Google OAuth built in, and a local CLI that runs on your own credentials.

Table of Contents

• MCP Server for Google Tag Manager
  • Table of Contents
  • Repository layout
  • Installation
    • Claude Desktop
    • Claude Code
    • VS Code
    • GitHub Copilot
    • Copilot CLI
    • Cursor
    • Antigravity
    • ChatGPT
    • Other MCP clients
    • Troubleshooting
  • Test your changes locally
    • Changes to `packages/core` or `packages/cli`
    • Changes to `apps/worker`
      • 1. Set up a Google Cloud OAuth client
      • 2. Configure local environment variables
      • 3. Start the server
      • 4. Point your MCP client at the local server
  • Releasing
  • Development

Repository layout

npm workspace with one app and two published packages:

Tools reach Google through a `GtmAuthProvider` (`getAccessToken(): Promise`) rather than through any particular session, which is what lets the same tool set back both servers — and a private one with your own auth. See the core package README.

Installation

This server comes in two flavours: Hosted server and Local CLI. Both give you the same 18 GTM tools; the difference is who handles Google auth.

If you're a contributor testing an unreleased change rather than just using the tools, skip everything below and see Test your changes locally instead.

Pick your client below. The hosted server needs the `mcp-remote` bridge on clients whose MCP support doesn't complete Google's OAuth flow natively; where a client does that itself, it connects straight to `https://gtm-mcp.stape.ai/mcp`.

Claude Desktop

⬇️ Click to expand ⬇️

Open Claude Desktop and navigate to Settings -> Developer -> Edit Config. This opens the configuration file that controls which MCP servers Claude can access.

Hosted server — restart Claude Desktop after saving; a browser window opens for the Google OAuth flow. Complete it to grant Claude access:

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gtm-mcp.stape.ai/mcp"
      ]
    }
  }
}

Local CLI — no OAuth flow, no data through anyone else's server, you supply a service account key or a refresh token:

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

See the CLI README for every credential option.

Claude Code

⬇️ Click to expand ⬇️

Claude Code speaks HTTP directly, including the OAuth handshake, so the hosted server needs no bridge.

Hosted server:

claude mcp add --transport http gtm-mcp-server https://gtm-mcp.stape.ai/mcp

A browser window opens for the Google OAuth flow the first time a tool is used. Run `/mcp` inside Claude Code to confirm it connected.

Local CLI:

claude mcp add gtm-mcp-server -e GOOGLE_SERVICE_ACCOUNT_KEY='{"type":"service_account", ... }' -- npx -y google-tag-manager-mcp-server

Both write into `.mcp.json` / your Claude Code MCP config.

VS Code

⬇️ Click to expand ⬇️

VS Code's MCP client supports HTTP servers and their OAuth flow natively, no `mcp-remote` needed. Add this to `.vscode/mcp.json`:

Hosted server:

{
  "servers": {
    "gtm-mcp-server": {
      "type": "http",
      "url": "https://gtm-mcp.stape.ai/mcp"
    }
  }
}

Local CLI:

{
  "servers": {
    "gtm-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

GitHub Copilot

⬇️ Click to expand ⬇️

GitHub Copilot Chat in VS Code uses VS Code's own MCP client, so it reads the same `.vscode/mcp.json` file — see VS Code above. No separate configuration is needed.

Copilot CLI

⬇️ Click to expand ⬇️

Copilot CLI also completes OAuth natively for remote HTTP servers. Add this to `~/.copilot/mcp-config.json`:

Hosted server:

{
  "mcpServers": {
    "gtm-mcp-server": {
      "type": "http",
      "url": "https://gtm-mcp.stape.ai/mcp"
    }
  }
}

Local CLI:

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

See GitHub's docs for the equivalent `copilot mcp add` subcommand.

Cursor

⬇️ Click to expand ⬇️

Cursor speaks HTTP directly too, no `mcp-remote` needed. Add this to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global — Settings → MCP → Add new global MCP server):

Hosted server:

{
  "mcpServers": {
    "gtm-mcp-server": {
      "url": "https://gtm-mcp.stape.ai/mcp"
    }
  }
}

A browser window opens for the Google OAuth flow the first time a tool is used.

Local CLI:

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

Antigravity

⬇️ Click to expand ⬇️

Antigravity's own OAuth support for remote HTTP servers doesn't reliably reach a token to the server yet (antigravity-cli#25), so use `mcp-remote` for the hosted server here too, the same way Claude Desktop does. Add this to `~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json` (workspace-local) — accessible from the editor's agent panel via … → MCP Servers → Manage MCP Servers → View raw config:

Hosted server:

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gtm-mcp.stape.ai/mcp"
      ]
    }
  }
}

Local CLI:

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

ChatGPT

⬇️ Click to expand ⬇️

1. In ChatGPT, enable Developer mode: Settings → Apps & Connectors → Advanced settings → Developer mode.

2. Go to Settings → Connectors → Create, and set the server URL to `https://gtm-mcp.stape.ai/mcp`.

3. Set Authentication to OAuth and complete the Google login in the browser window that opens.

ChatGPT only reaches servers over the public internet, it can't spawn a local process — so there's no Local CLI option here, only the hosted server.

Other MCP clients

⬇️ Click to expand ⬇️

Any other MCP-compatible client that expects a stdio-style `command`/`args` config can use the same `mcp-remote` block for the hosted server:

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gtm-mcp.stape.ai/mcp"
      ]
    }
  }
}

Or the local CLI directly, with your credentials:

{
  "mcpServers": {
    "gtm-mcp-server": {
      "command": "npx",
      "args": ["-y", "google-tag-manager-mcp-server"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\", ... }"
      }
    }
  }
}

Troubleshooting

MCP Server Name Length Limit

Some MCP clients (like Cursor AI) have a 60-character limit for the combined MCP server name + tool name length. If you use a longer server name in your configuration (e.g., `gtm-mcp-server-your-additional-long-name`), some tools may be filtered out.

To avoid this issue:

• Use shorter server names in your MCP configuration (e.g., `gtm-mcp-server`)

Clearing MCP Cache

If you're connecting through `mcp-remote` (Claude Desktop, Antigravity), it stores all the credential information inside `~/.mcp-auth` (or wherever your `MCP_REMOTE_CONFIG_DIR` points to). If you're having persistent issues, try running:

rm -rf ~/.mcp-auth

Then, restart your MCP client.

Test your changes locally

Which workflow you need depends on what you changed. Most changes are in the first

category — reach for the second only if you're touching the Worker itself.

Changes to `packages/core` or `packages/cli`

This is the tool logic itself (schemas, GTM API calls, error handling) — almost

everything you'd fix or add lives here. You don't need a Google Cloud OAuth client

or any Worker setup: build from source and run the CLI directly with credentials

you already have.

git clone https://github.com/stape-io/google-tag-manager-mcp-server
cd google-tag-manager-mcp-server
gh pr checkout    # or: git checkout 
npm install
npm run build

Point your MCP client at the local build instead of `npx` — same credential

options as the Claude Desktop Local CLI example above, an access

token from the OAuth Playground is

the fastest way to test a single change:

{
  "mcpServers": {
    "gtm-mcp-local": {
      "command": "node",
      "args": ["/absolute/path/to/google-tag-manager-mcp-server/packages/cli/dist/index.js"],
      "env": {
        "GOOGLE_ACCESS_TOKEN": "..."
      }
    }
  }
}

See the CLI README for every credential option.

Changes to `apps/worker`

Only needed for the hosted server's own code: the OAuth flow, routing, session

handling, the approval and status pages. This runs that code on your own machine

against your own Google Cloud OAuth credentials instead of `gtm-mcp.stape.ai`.

1. Set up a Google Cloud OAuth client

1. In the Google Cloud Console, create or select a project, then enable the Tag Manager API.

2. Go to APIs & Services > OAuth consent screen and configure it (External is fine). While the app is in Testing publishing status, only accounts listed as test users can log in.

3. Go to Audience, under Test users add your own Google account.

4. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID, type Web application.

5. Under Authorized redirect URIs, add `http://localhost:8788/callback`. (You can leave Authorized JavaScript origins empty — this flow is server-side only, no browser JS calls Google directly.)

6. Save, then copy the generated Client ID and Client secret.

2. Configure local environment variables

Copy the example file and fill in the values from the previous step:

cp apps/worker/.dev.vars.example apps/worker/.dev.vars

GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""
COOKIE_ENCRYPTION_KEY=""
WORKER_HOST="http://localhost:8788"
HOSTED_DOMAIN=""

`.dev.vars` is git-ignored — it's only used locally and never committed.

3. Start the server

npm install
npm run build
npm run dev

`npm run build` compiles the core package the Worker bundles against; `npm run dev` starts the Worker on `http://localhost:8788`.

4. Point your MCP client at the local server

Same as the Hosted server config above, but pointing at `localhost` instead of the hosted URL:

{
  "mcpServers": {
    "gtm-mcp-server-local": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8788/mcp"]
    }
  }
}

Restart Claude Desktop. A browser window will open for the Google OAuth flow; log in with the

account you added as a test user in step 1.

Note: if you've previously connected to the hosted server (or switch back and forth between

local and hosted), clear mcp-remote's cache first (see Troubleshooting above)

and fully restart your MCP client, otherwise it may reuse a stale/cached connection.

Releasing

Versions and changelogs are managed with Changesets. Along with a change that should ship, add:

npm run changeset

On merge to `main` the release workflow opens a "Version Packages" PR; merging that PR publishes to npm, core first and then the CLI that depends on it. The Worker is private and never published — it deploys from `main` on every push.

Development

npm install
npm run build      # core, then the CLI, then the Worker's generated version
npm run typecheck
npm run lint
npm run smoke      # starts the built CLI and runs an MCP handshake against it

Pull requests run all of the above plus a Worker bundle check, and flag changes to a published package that arrive without a changeset.

Both `@modelcontextprotocol/sdk` and `agents` are pinned to exact versions in `apps/worker`. The SDK identifies tool schemas with `instanceof`, so the whole workspace has to resolve a single copy, and `agents` releases pin the SDK version they were built against. Bump them together and deploy deliberately.