npm package: @pkbibi/gtm-mcp
Description: Google Tag Manager MCP server for building, auditing, diagnosing, and fixing GTM implementations
Author: Grow Online Digital
Latest version: 1.2.0

# gtm-mcp

A comprehensive Google Tag Manager MCP server for building, auditing, diagnosing, and fixing GTM implementations.

**75 tools** | **4 resources** | **3 workflow prompts**

## Features

- **Account & Container Management** - List accounts, create containers, get installation snippets
- **Workspace Management** - Create workspaces, check status, sync changes
- **Tag CRUD** - Create, read, update, delete tags (GA4, Google Ads, custom HTML, etc.)
- **Trigger CRUD** - Manage all trigger types (pageview, custom event, click, form, scroll, etc.)
- **Variable CRUD** - Manage user-defined and built-in variables
- **Folder Organisation** - Create folders, move entities for container governance
- **Version & Publishing** - Create versions, compare with live, publish
- **Version Diff & Rollback** - Compare versions/workspace vs live, publish rollback
- **Environment Management** - Manage staging/dev environments
- **User Permissions** - Grant and modify account/container access
- **Audit & Diagnosis** - Container health scores, broken tag detection, duplicate finding, naming convention checks, trigger analysis, GA4 validation
- **Consent Audit** - Identify tags missing Consent Mode settings
- **Server-side Clients** - List and manage server-side GTM clients
- **Google Ads Goals Audit** - List conversion actions and map website goals to GTM setup
- **GA4 Admin** - List accounts/properties and create properties/streams
- **Merchant Center** - Account status checks, product listings, disapproval audits
- **Builder Templates** - One-command setup for GA4, Google Ads conversions, consent mode, custom events, enhanced ecommerce

## Quick Start

### 1. Install

```bash
npm install -g gtm-mcp
```

Or run directly:

```bash
npx gtm-mcp
```

### 2. Configure Authentication

The server needs access to the Google Tag Manager API via a service account.

**Option A: Service account key file (recommended)**

```bash
export GTM_SERVICE_ACCOUNT_KEY_PATH="/path/to/service-account.json"
```

**Option B: Inline JSON key**

```bash
export GTM_SERVICE_ACCOUNT_KEY_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'
```

**Option C: Application Default Credentials**

```bash
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
# or run: gcloud auth application-default login
```

#### Service Account Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create or select a project
3. Enable the **Tag Manager API** (`tagmanager.googleapis.com`)
4. Create a **Service Account** under IAM & Admin > Service Accounts
5. Create a JSON key for the service account
6. In GTM, grant the service account email access to your GTM account (Admin > User Management)

#### Google Ads (Optional)

To use Google Ads audit tools, configure OAuth credentials and a developer token:

```bash
export GOOGLE_ADS_DEVELOPER_TOKEN="your-dev-token"
export GOOGLE_ADS_CLIENT_ID="your-oauth-client-id"
export GOOGLE_ADS_CLIENT_SECRET="your-oauth-client-secret"
export GOOGLE_ADS_REFRESH_TOKEN="your-refresh-token"
export GOOGLE_ADS_CUSTOMER_ID="1234567890"
# Optional (manager account):
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="0987654321"
```

**Multi-account:** The `GOOGLE_ADS_CUSTOMER_ID` is just the default. You can query any client account per-call by passing `customerId` to the Google Ads tools. All accounts under your MCC are accessible without configuration changes.

#### Merchant Center (Optional)

To use Merchant Center tools, grant the service account access to your Merchant Center account and set:

```bash
export MERCHANT_CENTER_ID="123456789"
```

#### Merchant Center Quick Example

Prompt:

```text
Audit Merchant Center disapprovals for merchant 123456789 and scan up to 1000 products.
```

Expected output shape:

```json
{
  "summary": {
    "totalChecked": 1000,
    "disapprovedCount": 42,
    "issueCategories": 7,
    "truncated": false
  },
  "topIssues": {
    "invalid_gtin": {
      "count": 12,
      "description": "Invalid GTIN",
      "items": ["Product A", "Product B"]
    }
  },
  "recommendation": "Fix these issues in the primary feed or via supplemental feeds to restore product visibility."
}
```

#### GA4 Admin Quick Example

Prompt:

```text
Create a GA4 property under accounts/123 and a web data stream for https://example.com.
```

Expected output shape (from `ga4_create_data_stream`):

```json
{
  "message": "Data stream created successfully",
  "streamName": "Web Stream",
  "name": "properties/123/dataStreams/456",
  "measurementId": "G-ABCDEFG123",
  "instruction": "Use 'gtm_setup_ga4' with measurementId 'G-ABCDEFG123' to configure this in GTM."
}
```

### 3. Connect to Claude

#### Claude Desktop

Add `gtm-mcp` to your `claude_desktop_config.json` alongside any existing MCP servers:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gtm-mcp": {
      "command": "npx",
      "args": ["-y", "gtm-mcp"],
      "env": {
        "GTM_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-dev-token",
        "GOOGLE_ADS_CLIENT_ID": "your-oauth-client-id",
        "GOOGLE_ADS_CLIENT_SECRET": "your-oauth-client-secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "0987654321",
        "MERCHANT_CENTER_ID": "123456789"
      }
    }
  }
}
```

Restart Claude Desktop after saving. Google Ads and Merchant Center env vars are optional.

#### Claude Code

```bash
claude mcp add gtm-mcp npx -- -y gtm-mcp \
  -e GTM_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json
```

Add `GOOGLE_ADS_*` and `MERCHANT_CENTER_ID` env vars if you plan to use those tools.

Or add a `.mcp.json` file to your project root:

```json
{
  "mcpServers": {
    "gtm-mcp": {
      "command": "npx",
      "args": ["-y", "gtm-mcp"],
      "env": {
        "GTM_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account.json"
      }
    }
  }
}
```

Add `GOOGLE_ADS_*` and `MERCHANT_CENTER_ID` env vars here if needed.

#### Claude.ai (Web)

Go to **Settings > Integrations > Add Custom MCP Server** and configure with command `npx`, args `-y gtm-mcp`, and the same environment variables.

**Security note:** Add `.mcp.json` to `.gitignore` to avoid committing credentials. Use `.mcp.example.json` as a template for others.

## Tool Reference

### Account & Container (5 tools)

| Tool | Description |
|------|-------------|
| `gtm_list_accounts` | List all accessible GTM accounts |
| `gtm_list_containers` | List containers in an account |
| `gtm_get_container` | Get container details |
| `gtm_create_container` | Create a new container |
| `gtm_get_container_snippet` | Get the GTM installation code snippet |

### Workspace (4 tools)

| Tool | Description |
|------|-------------|
| `gtm_list_workspaces` | List workspaces in a container |
| `gtm_create_workspace` | Create a new workspace |
| `gtm_get_workspace_status` | Get pending changes in a workspace |
| `gtm_sync_workspace` | Sync workspace with latest container version |

### Tags (5 tools)

| Tool | Description |
|------|-------------|
| `gtm_list_tags` | List all tags in a workspace |
| `gtm_get_tag` | Get full tag configuration |
| `gtm_create_tag` | Create a tag |
| `gtm_update_tag` | Update an existing tag |
| `gtm_delete_tag` | Delete a tag |

### Triggers (5 tools)

| Tool | Description |
|------|-------------|
| `gtm_list_triggers` | List all triggers in a workspace |
| `gtm_get_trigger` | Get full trigger configuration |
| `gtm_create_trigger` | Create a trigger |
| `gtm_update_trigger` | Update an existing trigger |
| `gtm_delete_trigger` | Delete a trigger |

### Variables (7 tools)

| Tool | Description |
|------|-------------|
| `gtm_list_variables` | List user-defined variables |
| `gtm_get_variable` | Get variable configuration |
| `gtm_create_variable` | Create a variable |
| `gtm_update_variable` | Update a variable |
| `gtm_delete_variable` | Delete a variable |
| `gtm_list_built_in_variables` | List enabled built-in variables |
| `gtm_enable_built_in_variables` | Enable built-in variable types |

### Server-side Clients (5 tools)

| Tool | Description |
|------|-------------|
| `gtm_list_clients` | List clients in a server-side workspace |
| `gtm_get_client` | Get full client configuration |
| `gtm_create_client` | Create a client |
| `gtm_update_client` | Update a client |
| `gtm_delete_client` | Delete a client |

### Folders (3 tools)

| Tool | Description |
|------|-------------|
| `gtm_list_folders` | List folders in a workspace |
| `gtm_create_folder` | Create a folder |
| `gtm_move_entities_to_folder` | Move tags/triggers/variables into a folder |

### Versions & Publishing (5 tools)

| Tool | Description |
|------|-------------|
| `gtm_list_versions` | List container versions |
| `gtm_get_version` | Get full version details |
| `gtm_get_live_version` | Get the currently published version |
| `gtm_create_version` | Create a version from workspace changes |
| `gtm_publish_version` | Publish a version to make it live |

### Version Diff & Rollback (5 tools)

| Tool | Description |
|------|-------------|
| `gtm_diff_versions` | Compare two container versions |
| `gtm_diff_workspace_to_live` | Compare workspace vs live version |
| `gtm_rollback_version` | Roll back by publishing a prior version |
| `gtm_export_container_version` | Export a container version snapshot |
| `gtm_import_container_version` | Import a container version into a workspace |

### Environments (3 tools)

| Tool | Description |
|------|-------------|
| `gtm_list_environments` | List environments |
| `gtm_create_environment` | Create a custom environment |
| `gtm_update_environment` | Update environment configuration |

### Permissions (3 tools)

| Tool | Description |
|------|-------------|
| `gtm_list_user_permissions` | List user permissions on an account |
| `gtm_create_user_permission` | Grant user access |
| `gtm_update_user_permission` | Modify user permissions |

### Audit & Diagnosis (7 tools)

| Tool | Description |
|------|-------------|
| `gtm_audit_container` | Comprehensive container audit with health score (0-100) |
| `gtm_find_broken_tags` | Identify broken or misconfigured tags |
| `gtm_find_duplicate_tags` | Detect redundant tracking |
| `gtm_check_naming_conventions` | Analyse naming pattern consistency |
| `gtm_analyze_triggers` | Check trigger configuration and usage |
| `gtm_validate_ga4_setup` | GA4-specific configuration validation |
| `gtm_audit_consent_settings` | Audit consent settings on tags |

### Google Ads (2 tools)

| Tool | Description |
|------|-------------|
| `gads_list_conversion_actions` | List Google Ads conversion actions (supports per-call `customerId` override) |
| `gads_audit_goals` | Audit goals and map website conversions to GTM (supports per-call `customerId` override) |

### GA4 Admin (4 tools)

| Tool | Description |
|------|-------------|
| `ga4_list_accounts` | List GA4 accounts accessible to the service account |
| `ga4_list_properties` | List GA4 properties (optionally filtered by account) |
| `ga4_create_property` | Create a new GA4 property under an account |
| `ga4_create_data_stream` | Create a GA4 web data stream and return the Measurement ID |

### Merchant Center (3 tools)

| Tool | Description |
|------|-------------|
| `gmc_get_account_status` | Check Merchant Center account status and policy issues |
| `gmc_list_products` | List products with status and item issues |
| `gmc_audit_disapprovals` | Summarize disapproved products and root causes (supports `maxResults`) |

Example:

```text
Audit Merchant Center disapprovals for merchant 123456789 and scan up to 1000 products.
```

### Builder Templates (5 tools)

| Tool | Description |
|------|-------------|
| `gtm_setup_ga4` | Create complete GA4 configuration (config tag + folder) |
| `gtm_setup_google_ads_conversion` | Set up Google Ads conversion tracking |
| `gtm_setup_custom_event` | Create custom event tracking (trigger + variables + GA4 event tag) |
| `gtm_setup_consent_mode` | Implement Consent Mode v2 with privacy-first defaults |
| `gtm_setup_ecommerce` | Set up enhanced ecommerce event tracking |

## Resources

| Resource | URI | Description |
|----------|-----|-------------|
| Tag Types Reference | `gtm://tag-types` | GTM tag type identifiers and configuration |
| Trigger Types Reference | `gtm://trigger-types` | GTM trigger types and filter options |
| Variable Types Reference | `gtm://variable-types` | GTM variable types and configuration |
| Naming Conventions | `gtm://naming-conventions` | Recommended naming convention guide |

## Workflow Prompts

| Prompt | Description |
|--------|-------------|
| `gtm_audit_workflow` | Step-by-step container audit (health score, broken tags, duplicates, naming, triggers, GA4) |
| `gtm_setup_workflow` | Guided new container setup (folders, variables, GA4, consent mode, snippet) |
| `gtm_debug_workflow` | Troubleshooting workflow for diagnosing tracking issues |

## Development

```bash
# Clone and install
git clone <repo-url>
cd gtm-mcp
npm install

# Build
npm run build

# Run in dev mode (with tsx)
npm run dev

# Run built version
npm start
```

## License

MIT