# gtm-mcp-server

An MCP (Model Context Protocol) server for creating and managing **tags, triggers, and
variables** in Google Tag Manager directly from Claude, Codex, or any MCP client.

The server only operates at the **workspace (draft) level** — it never auto-publishes a
container to production. You still need to review and publish the version yourself in
the GTM UI (or via a future extension of this tool).

## Features

- `gtm_list_accounts`, `gtm_list_containers`, `gtm_list_workspaces`
- `gtm_list_tags`, `gtm_create_tag`, `gtm_update_tag`, `gtm_delete_tag`
- `gtm_list_triggers`, `gtm_create_trigger`
- `gtm_list_variables`, `gtm_create_variable`

Every tool accepts `account` / `container` / `workspace` as either a name **or** an ID
(e.g. `container: "GTM-ABC123"` or `container: "My Website"`).

## 1. Create an OAuth client on Google Cloud

1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create (or select) a project.
2. Go to **APIs & Services → Library** and enable the **Tag Manager API**.
3. Go to **APIs & Services → Credentials → Create Credentials → OAuth client ID**.
   - Application type: **Desktop app**.
4. Download the resulting JSON file and rename it to `credentials.json`.
5. Place it at `~/.gtm-mcp/credentials.json` (default location), or set the
   `GTM_MCP_CREDENTIALS_PATH` environment variable to point somewhere else.

> The Google account you sign in with needs access to the relevant GTM account/container
> (add it under GTM → Admin → User Management if needed).

## 2. Install

```bash
git clone https://github.com/YOUR_USERNAME/gtm-mcp-server.git
cd gtm-mcp-server
npm install
npm run build
```

## 3. Sign in to Google (one-time)

```bash
npm run auth
```

This prints a URL — open it in your browser, sign in, and grant access. The token is
saved to `~/.gtm-mcp/token.json` and refreshes automatically afterwards (no need to
sign in again).

## 4. Connect to Claude Code / Claude Desktop

With Claude Code:

```bash
claude mcp add gtm -- node "/path/to/gtm-mcp-server/dist/index.js"
```

With Claude Desktop, add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gtm": {
      "command": "node",
      "args": ["/path/to/gtm-mcp-server/dist/index.js"]
    }
  }
}
```

Once connected, you can ask directly, for example:

> "Create a GA4 event tag named 'purchase_tracking' in container GTM-ABC123, default
> workspace, fired by the 'Purchase Event' trigger."

## Environment variables

| Variable | Default | Meaning |
|---|---|---|
| `GTM_MCP_CONFIG_DIR` | `~/.gtm-mcp` | Directory holding credentials/token |
| `GTM_MCP_CREDENTIALS_PATH` | `<config_dir>/credentials.json` | Path to the OAuth client secret file |
| `GTM_MCP_TOKEN_PATH` | `<config_dir>/token.json` | Path to the cached token |

## Security notes

- **Never commit** `credentials.json` or `token.json` to git (already covered by `.gitignore`).
- The token is stored in plaintext on your local machine — only run this server on a
  machine you trust.
- All changes are made at the workspace draft level; publishing still requires a manual
  step in the GTM UI.

## License

MIT