Skip to content
Back to search

gtm-mcp-server

An MCP server for Google Tag Manager. Connect it to your LLM, authenticate once, and start managing GTM through natural language.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/paolobietolini/gtm-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/paolobietolini/gtm-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/paolobietolini--gtm-mcp-server/badge.svg)](/listings/paolobietolini--gtm-mcp-server)

HTML

<a href="/listings/paolobietolini--gtm-mcp-server"><img src="/api/listings/paolobietolini--gtm-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Set `DASHBOARD_ENABLED=true` and restart the server to expose `/dashboard/`. The page shows the canonical MCP endpoint, server version, authentication setup status, and connection instructions. It is disabled by default.

The dashboard is public when enabled. It deliberately excludes tokens, sessions, account names, container data, and other GTM content. It reports server configuration only and does not verify the visitor's Google session.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 625 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # GTM MCP Server
  2. [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](LICENSE)
  3. [![Go](https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white)](https://go.dev/)
  4. [![MCP](https://img.shields.io/badge/MCP-Streamable_HTTP-8A2BE2)](https://modelcontextprotocol.io/)
  5. [![Security Checks](https://github.com/paolobietolini/gtm-mcp-server/actions/workflows/security.yml/badge.svg)](https://github.com/paolobietolini/gtm-mcp-server/actions/workflows/security.yml)
  6. [![GitHub release](https://img.shields.io/github/v/release/paolobietolini/gtm-mcp-server)](https://github.com/paolobietolini/gtm-mcp-server/releases)
  7. ---
  8. > [!IMPORTANT]
  9. > The hosted instance at https://mcp.gtmeditor.com will be shut down on November 30, 2026. See [#139](https://github.com/paolobietolini/gtm-mcp-server/issues/139) for details. Thanks to everyone who used it!
  10. ---
  11. GTM MCP Server connects MCP clients to the Google Tag Manager API. It can
  12. inspect containers, create and update workspace entities, create versions, and
  13. publish a selected version after explicit confirmation.
  14. Use the hosted server at:
  15. ```text
  16. https://mcp.gtmeditor.com
  17. ```
  18. The server supports browser-based Google OAuth for individual users and
  19. service-account authentication for self-hosted automation.
  20. ## Project status
  21. | Item | Current state |
  22. |---|---|
  23. | Version in `server.json` | `1.13.0` |
  24. | Transport | MCP Streamable HTTP, or stdio for local service-account use |
  25. | Runtime tools | 64 GTM tools by default; 94 with `GTM_TOOL_GROUPS=all`, plus 2 utility tools |
  26. | MCP resources | 8 resource definitions |
  27. | MCP prompts | 6 prompts |
  28. | Official GTM API coverage | 101 of 106 methods |
  29. | Hosted endpoint | `https://mcp.gtmeditor.com` |
  30. The project implements 101 methods from Google's 106-method GTM v2 discovery surface. The five `accounts.user_permissions` methods are intentionally excluded because granting and revoking GTM access are security-related and it shouldn't be manager by an LLM.
  31. ## Connect an MCP client
  32. Add the hosted URL as a remote HTTP MCP server. The client should discover the OAuth metadata, open Google sign-in, and reconnect with the issued bearer
  33. token.
  34. ### Claude Code
  35. ```bash
  36. claude mcp add --transport http gtm https://mcp.gtmeditor.com
  37. ```
  38. ### Gemini CLI
  39. ```bash
  40. gemini mcp add --transport http gtm https://mcp.gtmeditor.com
  41. ```
  42. Gemini CLI can also use this `settings.json` entry:
  43. ```json
  44. {
  45. "mcpServers": {
  46. "gtm": {
  47. "httpUrl": "https://mcp.gtmeditor.com"
  48. }
  49. }
  50. }
  51. ```
  52. ### Cursor
  53. Add the following to `.cursor/mcp.json`:
  54. ```json
  55. {
  56. "mcpServers": {
  57. "gtm": {
  58. "url": "https://mcp.gtmeditor.com"
  59. }
  60. }
  61. }
  62. ```
  63. ### ChatGPT, Codex, and Claude web
  64. Add a custom or remote MCP connection in the client and use
  65. `https://mcp.gtmeditor.com` as the server URL. Product menus change more often
  66. than this server, so refer to the client's current MCP connection instructions
  67. if the label differs.
  68. After connecting, try:
  69. ```text
  70. List my GTM accounts, containers, and workspaces. Do not make changes.
  71. ```
  72. The Google account used during OAuth determines which GTM accounts the server
  73. can access.
  74. ## Typical workflow
  75. 1. Call `list_accounts`, `list_containers`, and `list_workspaces` to discover
  76. IDs. Do not guess IDs.
  77. 2. Inspect the workspace with list/get tools or the `audit_container` prompt.
  78. 3. Create or update tags, triggers, variables, templates, clients, or
  79. transformations in the selected workspace.
  80. 4. Call `get_workspace_status` and resolve conflicts before versioning.
  81. 5. Call `create_version` to snapshot the workspace.
  82. 6. Inspect the saved version with `get_version`.
  83. 7. Call `publish_version` with `confirm: true` only when the selected version
  84. is ready to go live.
  85. 8. Verify the published state with `get_live_version`.
  86. Example requests:
  87. - "Audit this workspace for duplicate tags and unused triggers."
  88. - "Create a GA4 purchase event tag, but do not publish it."
  89. - "Show the difference between the latest saved version and the live version."
  90. - "Generate a Markdown tracking plan from this workspace."
  91. - "Import the iubenda template from the Community Template Gallery."
  92. ## Tools
  93. All GTM tools use the authenticated Google identity from the current MCP
  94. request. Inputs and outputs are structured JSON.
  95. ### Utility
  96. | Tool | Purpose |
  97. |---|---|
  98. | `ping` | Test MCP connectivity |
  99. | `auth_status` | Check whether the current request is authenticated |
  100. ### Accounts and containers
  101. | Tool | Purpose |
  102. |---|---|
  103. | `list_accounts` | List accessible GTM accounts |
  104. | `update_account` | Rename an account |
  105. | `list_containers` | List containers and their public IDs and settings |
  106. | `lookup_container` | Find a container by destination ID or GTM public tag ID |
  107. | `get_container_snippet` | Get a web install snippet or server-container configuration |
  108. | `create_container` | Create a web, app, AMP, or server container |
  109. | `update_container` | Rename a container while preserving its other settings |
  110. | `delete_container` | Permanently delete a container; requires `confirm: true` |
  111. | `combine_containers` | Merge a source container into a target; requires `confirm: true` |
  112. | `move_tag_id` | Move a tag ID into a new container; requires confirmation and terms acceptance |
  113. ### Workspaces
  114. | Tool | Purpose |
  115. |---|---|
  116. | `list_workspaces` | List workspaces in a container |
  117. | `create_workspace` | Create a workspace |
  118. | `get_workspace` | Get workspace metadata and its current fingerprint |
  119. | `update_workspace` | Update selected workspace fields |
  120. | `delete_workspace` | Delete a workspace; requires `confirm: true` |
  121. | `quick_preview_workspace` | Compile an ephemeral preview without saving or publishing |
  122. | `get_workspace_status` | Show pending changes and merge conflicts |
  123. | `bulk_update_workspace` | Apply multiple entity changes; requires `confirm: true` |
  124. | `resolve_workspace_conflict` | Replace a conflict with a resolved entity; requires `confirm: true` |
  125. | `sync_workspace` | Synchronize with the latest container version; requires `confirm: true` |
  126. Bulk update and conflict resolution accept raw GTM Entity JSON so every entity
  127. type supported by the official API remains available.
  128. ### Tags
  129. | Tool | Purpose |
  130. |---|---|
  131. | `list_tags` | List workspace tags |
  132. | `get_tag` | Get complete tag details |
  133. | `create_tag` | Create a tag |
  134. | `update_tag` | Update a tag with fingerprint-based concurrency control |
  135. | `delete_tag` | Delete a tag; requires `confirm: true` |
  136. ### Triggers
  137. | Tool | Purpose |
  138. |---|---|
  139. | `list_triggers` | List workspace triggers |
  140. | `get_trigger` | Get complete trigger details |
  141. | `create_trigger` | Create a trigger |
  142. | `update_trigger` | Update a trigger with fingerprint-based concurrency control |
  143. | `delete_trigger` | Delete a trigger; requires `confirm: true` |
  144. For `update_trigger`, omit `filterJson`, `customEventFilterJson`,
  145. `autoEventFilterJson`, or `parameterJson` to preserve the current field. Pass
  146. the JSON string `"[]"` to clear a field, or a non-empty JSON array to replace
  147. it. For click, link-click, and form-submission triggers, use `filterJson` because
  148. GTM drops `autoEventFilter` for those trigger types.
  149. ### Variables
  150. | Tool | Purpose |
  151. |---|---|
  152. | `list_variables` | List workspace variables |
  153. | `get_variable` | Get complete variable details |
  154. | `create_variable` | Create a variable |
  155. | `update_variable` | Update a variable with fingerprint-based concurrency control |
  156. | `delete_variable` | Delete a variable; requires `confirm: true` |
  157. ### Folders and built-in variables
  158. | Tool | Purpose |
  159. |---|---|
  160. | `list_folders` | List workspace folders |
  161. | `get_folder` | Get complete folder metadata |
  162. | `create_folder` | Create a folder |
  163. | `update_folder` | Update a folder with fingerprint protection |
  164. | `delete_folder` | Delete a folder; requires `confirm: true` |
  165. | `get_folder_entities` | List tags, triggers, and variables assigned to a folder |
  166. | `move_entities_to_folder` | Move tags, triggers, and variables; requires `confirm: true` |
  167. | `revert_folder` | Discard workspace folder changes; requires `confirm: true` |
  168. | `list_built_in_variables` | List enabled built-in variables |
  169. | `enable_built_in_variables` | Enable built-in variable types |
  170. | `disable_built_in_variables` | Disable built-in variable types; requires `confirm: true` |
  171. Use `revert_workspace_entity` to discard changes to a built-in variable.
  172. ### Zones
  173. | Tool | Purpose |
  174. |---|---|
  175. | `list_zones` | List all zones across every result page |
  176. | `get_zone` | Get boundary, child-container, and type-restriction configuration |
  177. | `create_zone` | Create a workspace zone |
  178. | `update_zone` | Update selected fields with fingerprint concurrency control |
  179. | `delete_zone` | Delete a zone; requires `confirm: true` |
  180. Use `revert_workspace_entity` to discard changes to a zone.
  181. ### Environments
  182. The `environments` tool group is optional. Enable it with
  183. `GTM_TOOL_GROUPS=all` or add `environments` to an explicit group list.
  184. | Tool | Purpose |
  185. |---|---|
  186. | `list_environments` | List all container environments across every result page |
  187. | `get_environment` | Get environment configuration and authorization metadata |
  188. | `create_environment` | Create a user environment |
  189. | `update_environment` | Update selected fields with fingerprint concurrency control |
  190. | `reauthorize_environment` | Rotate the authorization code; requires `confirm: true` |
  191. | `delete_environment` | Delete a user environment; requires `confirm: true` |
  192. The Live and Latest environments are managed by GTM. Creation and deletion
  193. apply to user environments; GTM permits URL and debug updates on other types.
  194. ### Destinations and Google tag configurations
  195. These tools are in the optional `destinations` and `gtag` groups.
  196. | Tool | Purpose |
  197. |---|---|
  198. | `list_destinations` | List Google tag destinations linked to a container |
  199. | `get_destination` | Get a destination by its link ID |
  200. | `link_destination` | Move a destination to a container; requires `confirm: true` |
  201. | `list_google_tag_configs` | List Google tag configurations in a workspace |
  202. | `get_google_tag_config` | Get a Google tag configuration |
  203. | `create_google_tag_config` | Create a Google tag configuration |
  204. | `update_google_tag_config` | Update a configuration with fingerprint protection |
  205. | `delete_google_tag_config` | Delete a configuration; requires `confirm: true` |
  206. Container combine, tag-ID move, and destination link operations do not copy or
  207. enable user permissions. Account permission management remains outside the
  208. current parity target.
  209. ### Custom templates
  210. | Tool | Purpose |
  211. |---|---|
  212. | `list_templates` | List custom templates |
  213. | `get_template` | Get template metadata and template code |
  214. | `create_template` | Create a custom template from `.tpl` code |
  215. | `update_template` | Update template code |
  216. | `delete_template` | Delete an unused template; requires `confirm: true` |
  217. | `import_gallery_template` | Import a Community Template Gallery template |
  218. | `get_tag_templates` | Return compact GA4 and Custom HTML input examples |
  219. | `get_trigger_templates` | Return compact trigger input examples |
  220. The full JSON examples live in the
  221. `gtm://best-practices/tool-input-formats` resource so every tool listing does
  222. not repeat them.
  223. ### Server-side containers
  224. | Tool | Purpose |
  225. |---|---|
  226. | `list_clients` | List server-container clients |
  227. | `get_client` | Get a client |
  228. | `create_client` | Create a client |
  229. | `update_client` | Update a client |
  230. | `delete_client` | Delete a client; requires `confirm: true` |
  231. | `list_transformations` | List transformations |
  232. | `get_transformation` | Get a transformation |
  233. | `create_transformation` | Create a transformation |
  234. | `update_transformation` | Update a transformation |
  235. | `delete_transformation` | Delete a transformation; requires `confirm: true` |
  236. Use `revert_workspace_entity` to discard changes to a client or transformation.
  237. ### Versions and publication
  238. | Tool | Purpose |
  239. |---|---|
  240. | `list_versions` | List all saved version headers across every result page |
  241. | `get_latest_version_header` | Get the latest saved header, which may differ from live |
  242. | `get_version` | Get a saved version and its complete entity collections |
  243. | `get_live_version` | Get the currently published version and its entities |
  244. | `create_version` | Create a version from a conflict-free workspace |
  245. | `publish_version` | Publish a selected version; requires `confirm: true` |
  246. | `update_version` | Update a saved version's name or description |
  247. | `delete_version` | Soft-delete a version; requires `confirm: true` |
  248. | `undelete_version` | Restore a soft-deleted version; requires `confirm: true` |
  249. | `set_latest_version` | Make a version Latest without publishing; requires `confirm: true` |
  250. ### Workspace reverts
  251. | Tool | Purpose |
  252. |---|---|
  253. | `revert_workspace_entity` | Discard workspace changes to a built-in variable, client, tag, template, transformation, trigger, variable, or zone; requires `confirm: true` |
  254. The tool fetches the current entity fingerprint before calling the matching
  255. official revert method. A successful result can have `existsAfterRevert: false`
  256. when the entity does not exist in the latest container version.
  257. ## Safety model
  258. - Delete operations, publication, and disabling built-in variables require
  259. `confirm: true`.
  260. - Update operations fetch the current resource fingerprint and use Google's
  261. optimistic concurrency checks.
  262. - `create_version` first checks that the workspace has changes and no merge
  263. conflicts.
  264. - Read tools distinguish latest saved state from published live state.
  265. - Google API errors are mapped to clearer not-found, permission, conflict, and rate-limit failures. Retryable API failures use bounded backoff.
  266. - MCP request bodies are limited to 5 MiB. OAuth and dynamic registration
  267. endpoints have stricter rate and body limits.
  268. Most entity edits affect a workspace and are not live until a version is
  269. published. Account and container operations act directly on those resources.
  270. Always review the target IDs and the generated version before publication.
  271. ## Resources
  272. The server exposes two concrete resources and six URI templates:
  273. | URI | Content |
  274. |---|---|
  275. | `gtm://accounts` | Accessible accounts |
  276. | `gtm://accounts/{accountId}/containers` | Containers |
  277. | `gtm://accounts/{accountId}/containers/{containerId}/workspaces` | Workspaces |
  278. | `gtm://accounts/{accountId}/containers/{containerId}/workspaces/{workspaceId}/tags` | Tags |
  279. | `gtm://accounts/{accountId}/containers/{containerId}/workspaces/{workspaceId}/triggers` | Triggers |
  280. | `gtm://accounts/{accountId}/containers/{containerId}/workspaces/{workspaceId}/variables` | Variables |
  281. | `gtm://best-practices` | Best-practice topic index |
  282. | `gtm://best-practices/{topic}` | One embedded guidance document |
  283. Best-practice topics include naming and organization, safe edits, GA4 and
  284. consent, server-side containers, and detailed tool input formats.
  285. ## Prompts
  286. | Prompt | Purpose |
  287. |---|---|
  288. | `audit_container` | Review tags, triggers, and variables for quality problems |
  289. | `generate_tracking_plan` | Build a Markdown tracking plan from a workspace |
  290. | `suggest_ga4_setup` | Recommend a GA4 structure from stated goals |
  291. | `find_gallery_template` | Guide Community Gallery discovery and import |
  292. | `best_practices_review` | Score a workspace against embedded guidance |
  293. | `plan_safe_edit` | Produce a staged edit/version/publish plan |
  294. Prompts prepare context and instructions for the model. They do not bypass tool authentication or mutation safeguards.
  295. ## Authentication
  296. ### Hosted OAuth
  297. The hosted server implements MCP OAuth discovery and Google authorization. It
  298. supports PKCE, Dynamic Client Registration, Client ID Metadata Documents,
  299. authorization-server metadata, and protected-resource metadata.
  300. The server never receives a Google password. It receives Google OAuth tokens
  301. after consent. A self-hosted operator can keep issued MCP and Google tokens
  302. across restarts by setting `TOKEN_STORE_PATH`; without that setting they remain in memory and disappear when the process stops.
  303. Expired MCP access tokens can be renewed transparently while their Google
  304. refresh credentials remain valid. `AUTH_AUTO_REFRESH_MAX_AGE` limits how long
  305. one bearer can be silently extended; its default is seven days.
  306. ### Service-account mode
  307. Service-account mode gives every holder of one server API key the GTM access
  308. granted to the configured Google service account.
  309. 1. Create a Google service account.
  310. 2. Add its email address to the required GTM account with only the permissions
  311. it needs.
  312. 3. Set a strong `SERVICE_ACCOUNT_API_KEY` on this server.
  313. 4. Set `GOOGLE_SERVICE_ACCOUNT_KEY_JSON` to the key JSON, or use Application
  314. Default Credentials on Google Cloud.
  315. 5. Configure the MCP client to send
  316. `Authorization: Bearer <SERVICE_ACCOUNT_API_KEY>`.
  317. OAuth and service-account mode can run together. Requests with the configured
  318. API key use the service account; OAuth users keep their own Google identity and GTM permissions.
  319. ### Stdio mode
  320. For a single local MCP client, the server can run over stdin/stdout instead of
  321. HTTP. The client starts the process when it needs GTM and stops it when the
  322. session ends, so no long-running server or API key is required. Stdio mode
  323. always uses service-account credentials:
  324. ```sh
  325. GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json gtm-mcp-server --stdio
  326. ```
  327. Claude Code example (`.mcp.json`):
  328. ```json
  329. {
  330. "mcpServers": {
  331. "gtm": {
  332. "command": "/usr/local/bin/gtm-mcp-server",
  333. "args": ["--stdio"],
  334. "env": {
  335. "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/sa.json",
  336. "GTM_TOOL_GROUPS": "all"
  337. }
  338. }
  339. }
  340. }
  341. ```
  342. `MCP_TRANSPORT=stdio` is equivalent to the `--stdio` argument. Logs go to
  343. stderr; stdout carries only MCP messages.
  344. ## Self-hosting
  345. ### Requirements
  346. - Go 1.26 or Docker
  347. - A Google Cloud project with the Tag Manager API enabled
  348. - A Google OAuth web client for user OAuth, or a Google service account for S2S
  349. - HTTPS and a stable public URL for remote OAuth deployments
  350. ### Google OAuth setup
  351. Create an OAuth 2.0 Web application in Google Cloud and add this authorized
  352. redirect URI:
  353. ```text
  354. https://your-host.example/oauth/callback
  355. ```
  356. The scheme and host must match `BASE_URL` exactly. For local development, use:
  357. ```text
  358. http://localhost:8080/oauth/callback
  359. ```
  360. ### Run from source
  361. ```bash
  362. git clone https://github.com/paolobietolini/gtm-mcp-server.git
  363. cd gtm-mcp-server
  364. cat > .env <<'EOF'
  365. BASE_URL=http://localhost:8080
  366. GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
  367. GOOGLE_CLIENT_SECRET=your-client-secret
  368. TOKEN_STORE_PATH=./data/tokens.json
  369. EOF
  370. go run .
  371. ```
  372. The repository reads `.env` and then `.env.local`; `.env.local` overrides
  373. `.env`. Both are ignored by Git.
  374. ### Run with Docker
  375. ```bash
  376. docker build -t gtm-mcp-server .
  377. docker run --rm \
  378. --name gtm-mcp-server \
  379. -p 8080:8080 \
  380. --env-file .env \
  381. -v gtm-mcp-tokens:/data \
  382. gtm-mcp-server
  383. ```
  384. When using the named volume, set `TOKEN_STORE_PATH=/data/tokens.json` in
  385. `.env`.
  386. ### Configuration
  387. | Variable | Default | Purpose |
  388. |---|---|---|
  389. | `PORT` | `8080` | HTTP listen port |
  390. | `BASE_URL` | `http://localhost:8080` | Canonical public URL used by OAuth metadata and callbacks |
  391. | `MCP_TRANSPORT` | `http` | `http` (Streamable HTTP) or `stdio`; the `--stdio` argument overrides it |
  392. | `MCP_STATELESS_HTTP` | `true` | Disable in-memory MCP HTTP sessions; required for MCP `2026-07-28` |
  393. | `DASHBOARD_ENABLED` | `false` | Expose the public connection setup page at `/dashboard/` |
  394. | `GOOGLE_CLIENT_ID` | empty | Google OAuth web-client ID |
  395. | `GOOGLE_CLIENT_SECRET` | empty | Google OAuth web-client secret |
  396. | `ACCESS_TOKEN_TTL` | `8h` | Lifetime of MCP access tokens |
  397. | `AUTH_AUTO_REFRESH_MAX_AGE` | `168h` | Maximum silent-renewal chain age |
  398. | `TOKEN_STORE_PATH` | empty | Optional persisted token-store file |
  399. | `SERVICE_ACCOUNT_API_KEY` | empty | Bearer API key that enables S2S mode |
  400. | `GOOGLE_SERVICE_ACCOUNT_KEY_JSON` | empty | Service-account JSON; omit when ADC is available |
  401. | `ALLOWED_HOSTS` | empty | Additional trusted hosts for Docker/internal URL resolution |
  402. | `TRUST_PROXY` | `false` | Trust the rightmost `X-Forwarded-For` hop for rate limiting |
  403. | `LOG_LEVEL` | `info` | Set `debug` for additional structured logs |
  404. | `GTM_TOOL_GROUPS` | current groups | Comma-separated tool families advertised through MCP |
  405. If OAuth and service-account credentials are both absent, the server starts in
  406. open mode. Use open mode only for isolated local development.
  407. Streamable HTTP is stateless by default: the server keeps no in-memory MCP
  408. session and ignores `Mcp-Session-Id`, so requests can reach any replica or
  409. survive a restart. This is required for MCP `2026-07-28` tool requests; legacy
  410. MCP `2025-11-25` clients remain supported. Stateless mode does not disable
  411. authentication: send credentials on every MCP request. Set
  412. `MCP_STATELESS_HTTP=false` only if a client depends on HTTP sessions or the
  413. GET event stream; this server makes no server-to-client requests.
  414. `TRUST_PROXY=true` is appropriate only when a trusted reverse proxy overwrites
  415. or appends `X-Forwarded-For`. The implementation uses the rightmost value. With
  416. multiple proxy hops, configure and test the trust boundary before relying on
  417. per-client rate limits.
  418. `ALLOWED_HOSTS` is a comma-separated allowlist used when the same server is
  419. reached through trusted internal Docker hostnames. Do not add arbitrary public hosts.
  420. `GTM_TOOL_GROUPS` controls schema size for clients that need only part of the
  421. API. Available groups are `accounts`, `workspaces`, `tags`, `triggers`,
  422. `variables`, `folders`, `builtins`, `zones`, `templates`, `server`, `guidance`,
  423. `environments`, `destinations`, `gtag`, `container-admin`, `folder-admin`, and
  424. `workspace-admin`, `version-admin`, and `reverts`. Leaving it unset preserves
  425. the established 64-tool surface. New parity groups are opt-in. Use `all` to
  426. include every current and future parity family, or select a subset:
  427. ```text
  428. GTM_TOOL_GROUPS=accounts,workspaces,tags,triggers,variables
  429. ```
  430. The two connection utility tools remain available regardless of this setting.
  431. ### Optional setup dashboard
  432. Set `DASHBOARD_ENABLED=true` and restart the server to expose `/dashboard/`.
  433. The page shows the canonical MCP endpoint, server version, authentication setup status, and connection instructions. It is disabled by default.
  434. The dashboard is public when enabled. It deliberately excludes tokens, sessions, account names, container data, and other GTM content. It reports server configuration only and does not verify the visitor's Google session.
  435. ## Releases and deployment
  436. `server.json` is the source of truth for the runtime version. It is embedded in the Go binary and returned by `/health`; there is no second version constant in Go code.
  437. To publish a release:
  438. 1. Update `server.json`.
  439. 2. Commit the release changes.
  440. 3. Push a matching tag such as `v1.11.0`.
  441. The release workflow rejects a tag that does not match `server.json`, creates
  442. cross-platform archives with GoReleaser, and then deploys the tagged source to the production VPS. The deployment uses the GitHub environment
  443. `auto-deployment` and expects these secrets:
  444. - `SSH_PRIVATE_KEY`
  445. - `VPS_KNOWN_HOSTS`
  446. - `VPS_HOST`
  447. - `VPS_USER`
  448. The workflow preserves server-only `.env`, `docker-compose.yml`, and token data, keeps a rollback image, rebuilds the service, and waits until `/health`reports the expected version.
  449. Recent commits on `main` can be newer than the latest tagged release. Check the [release page](https://github.com/paolobietolini/gtm-mcp-server/releases) when you need a reproducible published artifact.
  450. ## Development
  451. ```bash
  452. go test ./... -count=1
  453. go vet ./...
  454. staticcheck ./...
  455. go run ./cmd/tool-schema-report
  456. go run ./cmd/tool-schema-report -groups tags,zones
  457. ```
  458. The schema report prints the GTM tool count, serialized `tools/list` size, token
  459. estimate, and largest definitions. The default GTM tool surface serializes to
  460. 78,734 bytes for 64 tools. A regression test enforces an 80,000-byte ceiling so
  461. new parity work does not silently consume unlimited model context. The `all`
  462. group exposes 94 GTM tools and serializes to 115,748 bytes.
  463. Pull requests run `govulncheck`, `gosec`, Gitleaks, Trivy, `staticcheck`, and
  464. CodeQL. Request-level GTM tests use local fake Google endpoints. Mutating live
  465. tests must use a disposable container and clean up their entities.
  466. See [ARCHITECTURE.md](ARCHITECTURE.md) for package boundaries, request flow,
  467. authentication internals, token persistence, and security invariants.
  468. For a deep dive into the Google Tag Manager MCP server, read the [Deep Wiki](https://deepwiki.com/paolobietolini/gtm-mcp-server).
  469. ## Additional context
  470. - [`llms.txt`](llms.txt) is served at
  471. [`https://mcp.gtmeditor.com/llms.txt`](https://mcp.gtmeditor.com/llms.txt).
  472. - [`skills/gtm-mcp/gtm-mcp.md`](skills/gtm-mcp/gtm-mcp.md) contains a Claude
  473. Code skill with workflow guidance.
  474. - [`examples/gtm_agent.py`](examples/gtm_agent.py) demonstrates a programmatic
  475. MCP client.
  476. - [Google Tag Manager API v2 reference](https://developers.google.com/tag-platform/tag-manager/api/reference/rest)
  477. - [Model Context Protocol](https://modelcontextprotocol.io/)
  478. ## License
  479. BSD 3-Clause. See [LICENSE](LICENSE).
  480. Maintained by [Paolo Bietolini](https://github.com/paolobietolini).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.