gtm-mcp

MCP server to operate Google Tag Manager (GTM) from LLM clients.
Authentication uses Google OAuth 2.0.

Language

• English: README.md (this file)
• Japanese: README.ja.md

Features

• Generate OAuth consent URL, exchange auth code, check status, revoke auth
• Generic GTM API v2 call (gtm_request)
• Tag operations: list/create/update/delete
• Trigger operations: list/create/update/delete
• Variable operations: list/create/update/delete

Skills

• This repo includes a skill:
  • skills/gtm-mcp/SKILL.md
• It covers setup, MCP registration, first OAuth flow, and practical GTM tool usage.

Prerequisites

• Node.js 18+
• npm
• Codex CLI and/or Claude Code CLI (for MCP registration)
• Google Cloud OAuth client credentials

Google Cloud setup

1. Create or select a Google Cloud project
2. Enable Tag Manager API
3. Configure OAuth consent screen
4. Create an OAuth client ID
5. Add redirect URI: http://127.0.0.1:8085
6. Keep your Client ID and Client Secret

Setup after clone

git clone <this-repo-url>
cd gtm-mcp
npm install
npm run setup

npm run setup does:

• Create/update .env interactively
• Build TypeScript output (dist/)

Register MCP servers

Use only what you need:

npm run register:codex
npm run register:claude
npm run register:claude:local
npm run register:claude:user
npm run register:claude:project

Notes:

• register:claude registers in user scope (stored in ~/.claude.json)
• register:claude:local registers in local scope (stored in ~/.claude.json under project entry)
• register:claude:user is explicit user scope
• register:claude:project registers in project scope (.mcp.json)
• If gtm already exists, register:codex and register:claude* skip overwrite

From another directory:

npm --prefix /absolute/path/to/gtm-mcp run register:codex
npm --prefix /absolute/path/to/gtm-mcp run register:claude
npm --prefix /absolute/path/to/gtm-mcp run register:claude:local
npm --prefix /absolute/path/to/gtm-mcp run register:claude:user
npm --prefix /absolute/path/to/gtm-mcp run register:claude:project

register:claude:project uses the caller directory (INIT_CWD) as the project scope target.

First OAuth flow

Open a new Codex/Claude session, then:

1. Call oauth_get_consent_url
2. Open the returned URL in an external browser
3. Copy code from redirect URL
4. Call oauth_exchange_code with the code
5. Verify with oauth_status

Development

npm run dev

Production run

npm run build
npm start

.env example

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://127.0.0.1:8085
GTM_MCP_TOKEN_PATH=.gtm-mcp/tokens.json

Notes

• Tokens are stored at GTM_MCP_TOKEN_PATH
• Write operations require https://www.googleapis.com/auth/tagmanager.edit.containers