gtm-mcp

Google Tag Manager MCP Server

MCP server for Google Tag Manager API v2. Provides programmatic access to GTM accounts, containers, workspaces, tags, triggers, variables, and version management.

Requirements

• Node.js 18.0.0+
• Google Cloud Project with Tag Manager API enabled
• OAuth 2.0 credentials (Desktop application type)

Installation

Install from npm (Recommended)

npm install -g gtm-mcp

Or install locally:

npm install gtm-mcp

Install from source

git clone https://github.com/pouyanafisi/gtm-mcp.git
cd gtm-mcp
npm install
npm run build

Google Cloud Setup

• Enable Tag Manager API in Google Cloud Console
• Create OAuth 2.0 credentials (Desktop application)
• Download credentials JSON
• Save as credentials.json in gtm-mcp directory

Configuration

Using npm package

If installed globally, use the binary directly:

{
  "mcpServers": {
    "gtm": {
      "command": "gtm-mcp",
      "env": {
        "GTM_CREDENTIALS_FILE": "/absolute/path/to/credentials.json",
        "GTM_TOKEN_FILE": "/absolute/path/to/token.json"
      }
    }
  }
}

If installed locally, use npx:

{
  "mcpServers": {
    "gtm": {
      "command": "npx",
      "args": ["gtm-mcp"],
      "env": {
        "GTM_CREDENTIALS_FILE": "/absolute/path/to/credentials.json",
        "GTM_TOKEN_FILE": "/absolute/path/to/token.json"
      }
    }
  }
}

Using source installation

{
  "mcpServers": {
    "gtm": {
      "command": "node",
      "args": ["/absolute/path/to/gtm-mcp/dist/index.js"],
      "env": {
        "GTM_CREDENTIALS_FILE": "/absolute/path/to/gtm-mcp/credentials.json",
        "GTM_TOKEN_FILE": "/absolute/path/to/gtm-mcp/token.json"
      }
    }
  }
}

See MCP_SETUP.md for platform-specific instructions.

Authentication

Using npm package

If installed globally:

gtm-mcp-auth

Or with npx:

npx gtm-mcp-auth

Using source installation

npm run auth

Token saved to token.json and auto-refreshed.

Operations

99 operations available (95 API operations + 4 workflow helpers). See OPERATIONS.md for complete reference.

Categories

• Accounts: List, get, update accounts
• Containers: List, get, create, update, delete, snippet, lookup, combine, move tag ID
• Workspaces: List, get, create, update, delete, status, sync, resolve conflicts, bulk update, quick preview
• Tags: List, get, create, update, delete, revert
• Triggers: List, get, create, update, delete, revert
• Variables: List, get, create, update, delete, revert
• Built-in Variables: List, create, delete, revert
• Folders: List, get, create, update, delete, revert, move entities, get entities
• Container Versions: List, get, update, delete, undelete, set latest, get live, publish
• Version Headers: List, get latest
• Environments: List, get, create, update, delete, reauthorize
• User Permissions: List, get, create, update, delete
• Clients (Server-side): List, get, create, update, delete, revert
• Google Tag Config: List, get, create, update, delete, revert
• Templates: List, get, create, update, delete, revert, import from gallery
• Transformations (Server-side): List, get, create, update, delete, revert
• Zones (Server-side): List, get
• Workflows: GA4 setup, Facebook Pixel, form tracking, site-type workflows

Usage

List containers

List all containers for account 123456

Create GA4 setup

Create GA4 setup with measurement ID G-XXXXXXXXXX for account 123456, container 7890123

Update tag

Update tag 1 in account 123456, container 7890123 with new parameters

Publish changes

Publish version for account 123456, container 7890123 with name "Version 1.0"

GTM IDs

• Account ID: Numeric string (e.g., 123456)
• Container ID: Numeric string (e.g., 7890123)
• Workspace ID: Numeric string (e.g., 1 for default)
• Public Container ID: GTM-XXXXXXX format (not used by API)

Find IDs in GTM UI URL or container settings.

Project Structure

gtm-mcp/
├── src/
│   ├── index.ts              # MCP server
│   ├── gtm-client.ts         # GTM API client
│   ├── gtm-components.ts     # Workflow templates
│   ├── auth-helper.ts        # OAuth2 helper
│   └── auth.ts               # Auth script
├── docs/                      # API documentation
├── dist/                      # Compiled output
└── package.json

Development

npm run dev          # Watch mode
npm run type-check   # Type checking
npm run build        # Build
npm run auth         # Authenticate
npm test             # Run tests
npm run test:run     # Run tests once
npm run test:ui      # Test UI
npm run test:coverage # Coverage report

Documentation

• OPERATIONS.md - All 99 operations reference
• docs/ - GTM API v2 documentation
• API_COVERAGE.md - Implementation coverage
• MCP_SETUP.md - Setup instructions
• CONTRIBUTING.md - Contribution guidelines

Troubleshooting

Authentication fails: Run npm run auth separately. Verify credentials.json exists.

Permission errors: Verify account has edit access to container. Use numeric IDs, not GTM-XXX.

API errors: Check account/container IDs. Verify workspace exists. Check rate limits.

Build errors: Node.js 18+, run npm install, verify TypeScript config.

License

MIT