Samarth GTM MCP Server

A production-ready Model Context Protocol (MCP) server for the Google Tag Manager API v2, built for Samarth Analytics.

Gives Claude Desktop, Cursor, Claude Code, and any MCP-compatible client full, guarded access to GTM — read workspace contents, create/update tags/triggers/variables, audit implementations, publish versions, and more.

New: browser portal with live QC audit. A white-label, browser-based customer experience lives in apps/portal/. Customers sign in with Google OAuth, pick a GTM account/container/workspace, and run a live, read-only QC audit. Publishes still require Samarth approval. See the portal README for OAuth setup; run with npm run portal:dev.

---

Table of Contents

1. Features
2. Quick Start
3. Friendly Google Auth Options
4. Google Cloud OAuth Setup
5. Service Account Limitations
6. Environment Variables Reference
7. Guardrails
8. Available Tools
9. Claude Desktop Config
10. Cursor Config
11. Claude Code Config
12. Cloud Deployment
13. Security Notes
14. Development
15. Releases
16. Troubleshooting

---

Features

• Full GTM API v2 surface — accounts, containers, workspaces, tags, triggers, variables, folders, built-in variables, versions, sync, publish, preview
• Server-side & advanced GTM coverage — environments, user permissions, destinations, clients, transformations, zones, custom templates, gtag config, plus container snippet/lookup/combine/move-tag-id and workspace change-diff status
• GA4 coverage — GA4 Admin tools (ga4_*) plus GA4 Data API reporting (ga4_run_report, ga4_run_realtime_report) for intent-vs-reality reconciliation. Reads and reporting need only analytics.readonly; the GA4 Admin write tools are off by default behind GA4_MCP_ENABLE_WRITES / GA4_MCP_ENABLE_DELETES and additionally need analytics.edit
• Automatic pagination — every paginated list tool transparently follows nextPageToken to return all results, with optional maxPages/pageToken bounds
• Retry with exponential backoff + jitter — transient Google API failures (HTTP 408/429/5xx, network errors) on read requests are retried automatically; mutations are never auto-retried (tunable via GTM_MCP_RETRY_*)
• Two transport modes: stdio (local, for Claude Desktop/Cursor) and Streamable HTTP (cloud/team)
• Guardrails by default: read-only unless explicitly enabled; publish and delete gated separately
• Dry-run mode: simulate all writes without touching the API
• confirm=true required on all write/delete/publish operations
• Audit tool: inspects workspace for common GA4/GTM implementation issues
• Export tool: full workspace dump as structured JSON
• Zod schema validation on all inputs
• Detailed Google API error messages surfaced to the MCP client

---

Quick Start

Prerequisites

• Node.js ≥ 18
• A Google Cloud project with the Tag Manager API enabled
• A Google account with access to your GTM containers

Run with npx (no clone needed)

Once the package is on npm, the fastest path is:

# One-time OAuth onboarding (opens your browser; writes a local token file)
GOOGLE_OAUTH_CLIENT_ID=... GOOGLE_OAUTH_CLIENT_SECRET=... npx -y -p samarth-gtm-mcp samarth-gtm-auth

# Run the server (stdio)
npx -y samarth-gtm-mcp