# Google Tag Manager MCP Server ![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=flat-square&logo=node.js) ![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue?style=flat-square&logo=typescript) ![License](https://img.shields.io/badge/license-MIT-green?style=flat-square) ![GitHub stars](https://img.shields.io/github/stars/pouyanafisi/gtm-mcp?style=flat-square&logo=github) ![GitHub forks](https://img.shields.io/github/forks/pouyanafisi/gtm-mcp?style=flat-square&logo=github) 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) ```bash npm install -g gtm-mcp ``` Or install locally: ```bash npm install gtm-mcp ``` ### Install from source ```bash git clone https://github.com/pouyanafisi/gtm-mcp.git cd gtm-mcp npm install npm run build ``` ## Google Cloud Setup 1. Enable Tag Manager API in Google Cloud Console 2. Create OAuth 2.0 credentials (Desktop application) 3. Download credentials JSON 4. Save as `credentials.json` in `gtm-mcp` directory ## Configuration ### Using npm package If installed globally, use the binary directly: ```json { "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`: ```json { "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 ```json { "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: ```bash gtm-mcp-auth ``` Or with npx: ```bash npx gtm-mcp-auth ``` ### Using source installation ```bash npm run auth ``` Token saved to `token.json` and auto-refreshed. ## Operations 99 operations available (95 API operations + 4 workflow helpers). See [OPERATIONS.md](./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 ```bash 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](./OPERATIONS.md) - All 99 operations reference - [docs/](./docs/) - GTM API v2 documentation - [API_COVERAGE.md](./API_COVERAGE.md) - Implementation coverage - [MCP_SETUP.md](./MCP_SETUP.md) - Setup instructions - [CONTRIBUTING.md](./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