# GTM MCP Server

A Model Context Protocol (MCP) server for Google Tag Manager using **service account authentication** - no OAuth dance required.

## Features

- **No OAuth required** - Uses Google Service Account for authentication
- **Covers the core GTM workflow** - Accounts, Containers, Workspaces, Tags, Triggers, Variables, Built-In Variables, and Versions (29 tools)
- **Local & private** - Runs entirely on your machine
- **Works with Claude Desktop, Cursor, and other MCP clients**

## Quick Start

### 1. Create a Google Cloud Service Account

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Select or create a project
3. Enable the **Tag Manager API**:
   - Go to APIs & Services → Library
   - Search for "Tag Manager API"
   - Click Enable
4. Create a service account:
   - Go to IAM & Admin → Service Accounts
   - Click "Create Service Account"
   - Give it a name (e.g., "gtm-mcp-server")
   - Click Create and Continue (skip optional permissions)
   - Click Done
5. Create a key:
   - Click on your new service account
   - Go to Keys tab
   - Add Key → Create new key → JSON
   - Save the downloaded JSON file somewhere safe (e.g., `~/.config/gtm-service-account.json`)

### 2. Grant GTM Access to the Service Account

1. Go to [Google Tag Manager](https://tagmanager.google.com/)
2. Click Admin (gear icon)
3. Under Account, click "User Management"
4. Click the + button to add a user
5. Enter the service account email (looks like `name@project-id.iam.gserviceaccount.com`)
6. Set appropriate permissions:
   - **Read** - for listing/viewing only
   - **Edit** - for creating/modifying tags, triggers, variables
   - **Publish** - for publishing versions
   - **Admin** - for full access including user management

### 3. Configure Your MCP Client

#### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

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

#### Cursor

Add to your Cursor MCP settings:

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

### 4. Restart Your Client

After saving the config, restart your MCP client. You should see the GTM tools available.

## Available Tools

### Account Management
- `gtm_list_accounts` - List all accessible GTM accounts

### Container Management
- `gtm_list_containers` - List containers in an account
- `gtm_get_container` - Get container details

### Workspace Management
- `gtm_list_workspaces` - List workspaces in a container
- `gtm_create_workspace` - Create a new workspace
- `gtm_get_workspace_status` - Show pending changes and merge conflicts in a workspace
- `gtm_sync_workspace` - Sync a workspace to the latest container version

### Tag Management
- `gtm_list_tags` - List all tags in a workspace
- `gtm_get_tag` - Get full tag details with parameters
- `gtm_create_tag` - Create a new tag
- `gtm_update_tag` - Update an existing tag
- `gtm_delete_tag` - Delete a tag

### Trigger Management
- `gtm_list_triggers` - List all triggers in a workspace
- `gtm_get_trigger` - Get full trigger details
- `gtm_create_trigger` - Create a new trigger
- `gtm_update_trigger` - Update an existing trigger
- `gtm_delete_trigger` - Delete a trigger

### Variable Management
- `gtm_list_variables` - List all variables in a workspace
- `gtm_get_variable` - Get full variable details
- `gtm_create_variable` - Create a new variable
- `gtm_update_variable` - Update an existing variable
- `gtm_delete_variable` - Delete a variable

### Built-In Variable Management
- `gtm_list_built_in_variables` - List enabled built-in variables
- `gtm_enable_built_in_variables` - Enable built-in variables (e.g. Page URL, Click Classes)
- `gtm_disable_built_in_variables` - Disable built-in variables

### Version Management
- `gtm_list_versions` - List container versions
- `gtm_get_live_version` - Get the currently live (published) version
- `gtm_create_version` - Create a version from a workspace
- `gtm_publish_version` - Publish a version to make it live

All list tools return results one page at a time; when more results exist, the response includes a `page_token` to pass to the next call.

## Usage Examples

Once configured, you can ask Claude things like:

- "List my GTM accounts"
- "Show me all containers in account 123456"
- "What tags are in my website container?"
- "Create a new pageview trigger called 'All Pages'"
- "Create a custom HTML tag that fires on all pages"
- "Create a version and publish it"

## Troubleshooting

### "GOOGLE_APPLICATION_CREDENTIALS not set"
Make sure the environment variable is set in your MCP client config and points to a valid JSON key file.

### "Permission denied" errors
- Verify the service account email has been added to your GTM account
- Check that the permission level is sufficient for the operation

### "API not enabled" errors
Make sure the Tag Manager API is enabled in your Google Cloud project.

### Server not appearing in Claude Desktop
- Check that the paths in your config are correct
- Look at Claude Desktop's MCP logs for errors
- Try running `npx gtm-mcp-server` directly to see any error messages

## Development

```bash
# Clone the repository
git clone https://github.com/alexstansfield/gtm-mcp-server.git
cd gtm-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Watch mode for development
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js
```

## License

MIT