Samarth GTM MCP Server

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

Use it through Samarth Desktop - the local Electron app with a chat UI that embeds this server (Quick Start). 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. Google Cloud OAuth Setup
4. Service Account Limitations
5. Environment Variables Reference
6. Guardrails
7. Available Tools
8. Cloud Deployment
9. Security Notes
10. Development
11. Releases
12. 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

The way to run Samarth is the desktop app - a local Electron app with a chat UI that embeds the MCP server in-process. Multi-account Google sign-in, per-account LLM keys (OpenAI / Anthropic / Gemini), secrets in the OS keychain. Nothing to configure by hand: the Google OAuth client and your LLM key are entered in the app on first run.

You need: Node.js 18 or newer, Git, and a free Google "Desktop app" OAuth client - two values you create once in your Google Cloud project (exact click-by-click steps).

git clone https://github.com/samarthanalytics-sj/samarth-analytics-mcp.git
cd samarth-analytics-mcp/apps/desktop
npm install    # downloads the Electron binary (~100 MB first time)
npm run dev

The window opens; paste your OAuth client ID + secret and an LLM API key when asked, sign in to Google, and start chatting with your GTM / GA4 setup.

Prefer a config file over typing in the app? Put the OAuth client in a .env file instead - the app reads it on launch (values typed in the app and real shell variables always take precedence):

GOOGLE_DESKTOP_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_DESKTOP_CLIENT_SECRET=your-client-secret

Save it as apps/desktop/.env or at the repo root (already gitignored - never commit it). A repo-root .env using the server's GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET names works too, so one file can serve both the app and the MCP server. A packaged install reads .env from its data directory instead (%APPDATA% on Windows).

Your everyday launch afterwards is just:

cd samarth-analytics-mcp/apps/desktop && npm run dev

Full guide - Windows/macOS specifics, first-run setup, building a real .exe/.dmg installer, and the Error: Electron uninstall fix: apps/desktop/INSTALL.md.

Google Cloud OAuth Setup

Step 1: Enable the GTM API

1. Go to Google Cloud Console
2. Select or create a project
3. Navigate to APIs & Services → Library
4. Search for "Tag Manager API" and click Enable
5. Search for "Google Analytics Admin API" and click Enable (required for the read-only ga4_* Admin tools)
6. Search for "Google Analytics Data API" and click Enable (required for ga4_run_report / ga4_run_realtime_report)

Step 2: Create OAuth 2.0 Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth 2.0 Client ID
3. Choose application type:
   • Desktop app — simplest for local stdio use (no redirect URI needed)
   • Web application — for the HTTP server (add your redirect URI)
4. Download the JSON or copy the Client ID and Client Secret
5. Add to .env:
   Code

   Copy

   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_REDIRECT_URI=http://localhost:3001/oauth/callback
   

Step 3: Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Choose External (or Internal if you have Google Workspace)
3. Fill in App name, support email
4. Add scopes:
   • https://www.googleapis.com/auth/tagmanager.readonly
   • https://www.googleapis.com/auth/tagmanager.edit.containers
   • https://www.googleapis.com/auth/tagmanager.edit.containerversions
   • https://www.googleapis.com/auth/tagmanager.manage.accounts
   • https://www.googleapis.com/auth/tagmanager.manage.users
   • https://www.googleapis.com/auth/tagmanager.publish
   • https://www.googleapis.com/auth/analytics.readonly (read-only GA4 Admin and Data API tools)
   • https://www.googleapis.com/auth/analytics.edit (GA4 Admin write tools — gated by GA4_MCP_ENABLE_WRITES)
   • https://www.googleapis.com/auth/analytics.manage.users (GA4 access-binding write tools)
5. Add your Google account as a test user (while the app is in "testing" mode)

Note: For personal/agency use, keeping the app in "Testing" mode is fine. You will need to re-authorize every 7 days unless you publish the app or get it verified.

Step 4: Run OAuth Setup

npm run auth:google

Or, if you prefer the older paste-the-code helper:

npm run oauth:setup

Service Account Limitations

Short version: Service accounts do NOT work with GTM by default. Use OAuth 2.0.

The Google Tag Manager API is a user-data API — it manages resources owned by individual Google accounts. Service accounts are not Google users and are not automatically granted access to GTM containers.

Option A: Add the service account as a GTM user (simplest)

If you still want to use a service account:

1. Get the service account email (e.g., my-sa@project.iam.gserviceaccount.com)
2. In GTM, go to Admin → User Management at the account or container level
3. Add the service account email with the appropriate role (Read, Edit, Approve, Publish)
4. Set GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/key.json in .env

Caveats: This only works if the GTM container is associated with a Google account, not a Google Workspace that restricts external sharing.

Option B: Domain-Wide Delegation (Google Workspace only)

For Google Workspace organizations:

1. Create a service account with a JSON key
2. Enable Domain-Wide Delegation on the service account in Google Cloud Console
3. In Google Workspace Admin Console → Security → API Controls → Domain-wide Delegation:
   • Add the service account client ID
   • Add scopes: https://www.googleapis.com/auth/tagmanager.edit.containers (and others as needed)
4. In .env, set:
   Code

   Copy

   GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/key.json
   

5. The server will impersonate the user automatically if you set a subject in buildGoogleAuth()

Caveats: Requires a paid Google Workspace account. Only available for your own domain.

Environment Variables Reference