Google Tag Manager + read-only GA4 MCP server. Read-only by default, gated writes, audits.
Samarth GTM MCP Server
Samarth GTM MCP Server (io.github.samarthanalytics-sj/samarth-gtm-mcp) is a Model Context Protocol (MCP) server for the Google Tag Manager API v2. It provides read-only access by default, with gated writes and audits, and is intended for use with Samarth Desktopβs embedded chat UI.
π οΈ Key Features
Google Tag Manager API v2 support
Model Context Protocol (MCP) server
Read-only by default
Writes gated (guarded access) with audits
π Use Cases
Read GTM workspace contents
Manage GTM elements by creating and updating tags and trigger configurations (with write gating)
β‘ Developer Benefits
Designed for production use
Accessible via Samarth Desktop (local Electron app with chat UI)
An open-source Model Context Protocol (MCP) server that lets AI assistants such as Claude Desktop, Claude Code and Cursor work with Google Tag Manager and GA4. It covers the full GTM API v2 surface (100+ tools, including server-side containers), the GA4 Admin and Data APIs, a built-in implementation audit, and a second server that crawls a website to check its tags and Consent Mode v2 setup. Built by Samarth Analytics for our own client work and released under the MIT license for the analytics community.
Read-only by default. Creating, updating, publishing and deleting are each behind a separate environment flag, every write also requires confirm=true, and a dry-run mode simulates writes without touching the API. See Guardrails.
Use it at your own risk, and start on a dummy container. The server acts with your Google credentials, so every change it makes is yours. Try it first on a sandbox GTM container and a test GA4 property, keep the write flags off until you have watched how it behaves, and review the container's version history after any write session. We run it in production, but your setup is not ours.
Three ways to use it
What you get
Where to start
Hosted, no install
Our community instance at https://mcp.samarthanalytics.com/mcp. Sign in with your own Google account; it only sees your containers and properties, and it is locked to read-only. Shared, best-effort, no uptime promise.
Add it to your MCP client with mcp-remote: {"mcpServers":{"samarth-gtm":{"command":"npx","args":["mcp-remote@next","https://mcp.samarthanalytics.com/mcp"]}}}
Local
The server on your machine over stdio, with your own Google OAuth client, and the write flags under your control.
The repo also ships Samarth Desktop, a local Electron app with a chat UI that embeds this server (Quick Start), and a browser-based customer portal in apps/portal/ that runs live, read-only QC audits.
Contributions are welcome. Bug reports with a reproducible container setup are the most useful thing you can send. Read CONTRIBUTING.md first; CI runs on every pull request.
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).
bash
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):
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:
bash
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.
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
bash
npm run auth:google
Or, if you prefer the older paste-the-code helper:
bash
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:
Get the service account email (e.g., my-sa@project.iam.gserviceaccount.com)
In GTM, go to Admin β User Management at the account or container level
Add the service account email with the appropriate role (Read, Edit, Approve, Publish)
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.
Hosted-only. Samarth-owned public OAuth client. Takes precedence over the self-hosted vars when set.
SAMARTH_GOOGLE_OAUTH_CLIENT_SECRET
β
Hosted-only. Inject from your platform secret manager. Never commit.
GOOGLE_ACCESS_TOKEN
β
Current OAuth access token. Env vars take precedence over the token file.
GOOGLE_REFRESH_TOKEN
β
OAuth refresh token (long-lived). Env vars take precedence over the token file.
GTM_MCP_TOKEN_FILE
./.gtm-mcp-tokens.json
Path to the local OAuth token file written by npm run auth:google (gitignored).
GOOGLE_SERVICE_ACCOUNT_KEY_FILE
β
Path to service account JSON key (see limitations above)
GTM_MCP_TRANSPORT
stdio
Transport: stdio or http
GTM_MCP_HTTP_PORT
3001
HTTP server port (http transport only; falls back to PORT)
GTM_MCP_HTTP_AUTH_TOKEN
β
Bearer token gating /mcp (http transport). With neither this nor STYTCH_PROJECT_ID set, the HTTP transport refuses to start.
GTM_MCP_HTTP_ALLOW_UNAUTHENTICATED
false
Local-dev opt-in to start without auth. Binds loopback only unless GTM_MCP_HTTP_HOST overrides.
GTM_MCP_HTTP_HOST
β
Bind host. Defaults to loopback when unauthenticated, all interfaces when authenticated.
STYTCH_PROJECT_ID
β
Setting this switches the HTTP transport to multi-user mode: each /mcp request carries a Stytch JWT resolved to that user's own Google identity. Unset = single-identity mode. Pin STYTCH_JWT_ISSUER / STYTCH_JWT_AUDIENCE in production (see .env.example).
STYTCH_SECRET
β
Stytch project secret (server-only). Required when STYTCH_PROJECT_ID is set β the server exits without it.
STYTCH_PUBLIC_TOKEN
β
Publishable token powering the /oauth/authorize page. Not a secret.
GTM_MCP_PUBLIC_URL
http://localhost:<port>
This server's public origin, advertised in the OAuth Protected Resource Metadata document.
GTM_MCP_ENABLE_WRITES
false
Allow create/update operations
GTM_MCP_ENABLE_PUBLISH
false
Allow publish operations
GTM_MCP_ENABLE_DELETES
false
Allow delete operations
DRY_RUN
false
Simulate all writes without calling the API
GTM_MCP_RETRY_MAX
3
Retry attempts for transient read failures (408/429/5xx, network). 0 disables retries. Mutations are never auto-retried.
GTM_MCP_RETRY_MAX_DELAY_MS
30000
Cap on a single backoff sleep (exponential backoff with jitter)
GTM_MCP_RETRY_TOTAL_TIMEOUT_MS
60000
Cap on total wall time from first request to last retry
Guardrails
The server enforces three independent guardrails in addition to the confirm=true requirement:
Guardrail
Env Variable
What it gates
Write guard
GTM_MCP_ENABLE_WRITES=true
All create and update operations
Delete guard
GTM_MCP_ENABLE_DELETES=true
All delete operations
Publish guard
GTM_MCP_ENABLE_PUBLISH=true
All version publish operations
Dry run
DRY_RUN=true
Simulate without API calls (overrides all)
confirm=true is always required on write/delete/publish tools regardless of env settings. This prevents accidental modifications even when guardrails are enabled.
Recommended Configurations
Read-only exploration (default β safe for sharing with team):
Look up a container by linked destination/tag ID (e.g. G-XXXX)
containers_combine
βοΈ Combine (merge) another container into this one
containers_move_tag_id
βοΈ Move a Tag ID out into a new container
Destinations
Tool
Description
destinations_list
List linked destinations (Google tags / GA4) for a container
destinations_get
Get a specific destination
destinations_link
βοΈ Link a destination to a container
Workspaces
Tool
Description
workspaces_list
List workspaces in a container (auto-paginated)
workspaces_get
Get a specific workspace
workspaces_create
βοΈ Create a new workspace
workspace_get_status
Review the change diff (changed entities + merge conflicts) before versioning
workspace_sync
βοΈ Sync workspace to latest container version
workspace_resolve_conflict
βοΈ Resolve a merge conflict
workspace_quick_preview
Generate a preview link (read-safe)
workspace_create_version_and_publish
π Create version + publish in one step
Tags
Tool
Description
tags_list
List all tags in a workspace
tags_get
Get a specific tag
tags_create
βοΈ Create a tag
tags_update
βοΈ Update a tag
tags_delete
ποΈ Delete a tag
Triggers
Tool
Description
triggers_list
List all triggers
triggers_get
Get a specific trigger
triggers_create
βοΈ Create a trigger
triggers_update
βοΈ Update a trigger
triggers_delete
ποΈ Delete a trigger
Variables
Tool
Description
variables_list
List all user-defined variables
variables_get
Get a specific variable
variables_create
βοΈ Create a variable
variables_update
βοΈ Update a variable
variables_delete
ποΈ Delete a variable
Folders
Tool
Description
folders_list
List all folders
folders_get
Get a specific folder
folders_entities
List entities in a folder (auto-paginated)
folders_create
βοΈ Create a folder
folders_update
βοΈ Update a folder
folders_delete
ποΈ Delete a folder
folders_move_entities
βοΈ Move entities into a folder
Built-In Variables
Tool
Description
built_in_variables_list
List enabled built-in variables
built_in_variables_enable
βοΈ Enable built-in variables
built_in_variables_disable
ποΈ Disable built-in variables
built_in_variables_revert
βοΈ Revert a built-in variable to base version
Versions
Tool
Description
versions_list
List version headers
versions_get
Get a version (pass "live" for current live version)
versions_create
βοΈ Create a checkpoint version from workspace
versions_set_latest
βοΈ Set a version as latest
versions_publish
π Publish a specific version
versions_undelete
βοΈ Undelete a version
versions_delete
ποΈ Delete a version
Environments
Tool
Description
environments_list
List environments in a container (auto-paginated)
environments_get
Get a specific environment
environments_create
βοΈ Create an environment
environments_update
βοΈ Update an environment
environments_reauthorize
π Re-generate the environment authorization token (high-impact)
environments_delete
ποΈ Delete an environment
User Permissions (account-level)
Tool
Description
user_permissions_list
List user permissions for an account (auto-paginated)
user_permissions_get
Get a specific user permission
user_permissions_create
βοΈ Grant a user account/container access
user_permissions_update
βοΈ Update a user's access levels
user_permissions_delete
ποΈ Revoke a user's access
Server-Side & Advanced Container Resources
These are workspace-scoped resources from GTM API v2. Create/update accept the full
resource as a JSON string (bodyJson) since their bodies are deeply nested. Each
supports *_list (auto-paginated), *_get, *_create βοΈ, *_update βοΈ, *_delete ποΈ,
and (except gtag_config) *_revert βοΈ.
Resource
Tools
Notes
Clients
clients_*
Server container request clients
Transformations
transformations_*
Server container event transformations
Zones
zones_*
Zone delegation
Templates
templates_*
Custom / gallery-installed templates
Gtag Config
gtag_config_*
Google tag (gtag) configuration β no revert
Analytics & Export
Tool
Description
audit_container
Inspect workspace for analytics issues
export_container
Export workspace as structured JSON
GA4 Admin (read-only)
Read-only wrappers over the Google Analytics Admin API (v1beta, with a single
v1alpha call for enhanced measurement). These never write, update, or delete GA4
resources and require no confirm flag. They power the senior audit framework's
GA4_ADMIN checks (custom dimensions/metrics, data streams & measurement IDs, data
retention, enhanced measurement, key events, Google Ads links).
Requires the https://www.googleapis.com/auth/analytics.readonly scope and the
Google Analytics Admin API enabled in your Google Cloud project. A 403 mentioning
scope means you should re-run npm run auth:google.
Tool
Description
ga4_account_summaries_list
List GA4 accounts + their property summaries (best discovery entry point)
ga4_properties_list
List properties under a parent account (display name, time zone, currency, service level)
ga4_property_get
Get a single property by ID
ga4_data_streams_list
List data streams (web/Android/iOS) incl. web measurement IDs
ga4_enhanced_measurement_get
Get enhanced measurement settings for a web data stream (v1alpha)
ga4_custom_dimensions_list
List custom dimensions (parameter, scope)
ga4_custom_metrics_list
List custom metrics (parameter, unit, scope)
ga4_data_retention_get
Get event data-retention settings
ga4_key_events_list
List key events (formerly "conversion events" β current Admin naming)
ga4_google_ads_links_list
List Google Ads links (customer ID, auto-tagging/ads-personalization flags)
Accepts either a bare numeric ID (123456789) or the fully-qualified form
(properties/123456789, accounts/123456) wherever a property/account is required.
Documented limitations (not exposed by the GA4 Admin API v1beta, so intentionally
not implemented rather than faked):
Internal-traffic / unwanted-referral data filters β no public dataFilters collection; configured per data stream.
Referral exclusions β no dedicated Admin API resource.
Channel groups and audiences β exist only on the v1alpha surface and are out of scope for this read-only v1beta set.
GA4 Data API (read-only reporting)
Read-only wrappers over the Google Analytics Data API (v1beta). They never
write and require no confirm flag. Use them to reconcile intent vs. reality β
comparing the events a container is configured to send against the events GA4
actually reports (zero reported activity for a configured event is a red flag).
These use the samehttps://www.googleapis.com/auth/analytics.readonly scope
as the GA4 Admin tools, so no extra consent is needed. Enable the Google
Analytics Data API in your Google Cloud project.
Tool
Description
ga4_run_report
Run a report over a date range (dimensions + metrics, e.g. eventCount by eventName); supports limit, offset, and ordering
ga4_run_realtime_report
Run a Realtime report (events in roughly the last 30 minutes) for live QA
Documented gaps (intentionally not exposed rather than faked): pivot reports,
cohorts, and funnels.
Pagination
All list tools backed by paginated GTM endpoints (accounts_*-scoped containers,
workspaces, tags, triggers, variables, folders, folder entities, environments,
user permissions, clients, transformations, zones, templates, gtag configs)
auto-follow pagination and return all results by default. Optional arguments:
maxPages β cap the number of API pages fetched (default 50). If more pages remain,
the response includes "truncated": true and a nextPageToken.
pageToken β resume from a previous truncated result.
Non-truncated responses keep the original { <key>: [...], count } shape unchanged.
Two tools differ, because one list key does not describe what they return:
folders_entities returns three parallel collections (tag, trigger, variable, always
present, empty when the folder has none) plus a counts object, and adds truncated /
nextPageToken only when the page ceiling was hit.
export_container pages five collections independently, so it takes maxPages (applied per
collection) but no pageToken. A short export is marked incomplete: true with
truncatedCollections, per-collection nextPageTokens and a warning β in every format,
including the default summary.
All βοΈ ποΈ π tools also require confirm: true in the tool arguments.
Cloud Deployment
Transport
For cloud deployments, use GTM_MCP_TRANSPORT=http. The server exposes:
POST /mcp β Streamable HTTP MCP endpoint
GET /mcp β SSE stream for existing sessions
DELETE /mcp β Session termination
GET /health β Health check
There is no /oauth/callback route on this server. npm run auth:google runs its own short-lived listener on 127.0.0.1:3001 for the redirect; an unauthenticated callback on the hosted transport could overwrite the server's stored Google credentials, so it was removed.
Connecting Remote Clients
Clients that support Streamable HTTP can connect directly to the /mcp endpoint. For clients that only support stdio (like Claude Desktop), use mcp-remote as a proxy:
Limitation: Vercel Serverless Functions have a 10-second timeout (hobby) / 60-second (pro). Stateful SSE sessions require persistent connections which Vercel does not support well. Use Vercel only for stateless MCP interactions. Recommended alternative: Vercel + external session store (Redis/Upstash), or use Render/Fly.io instead.
For Vercel, export the Express app as a serverless handler:
ts
// api/mcp.tsexportdefault app; // where app is the Express instance
Set env vars in Vercel Dashboard β Settings β Environment Variables.
Minimum scopes β If you only need read access, revoke write scopes by removing them from the OAuth consent screen and re-authorizing. The server reads fine with tagmanager.readonly only.
Cloud deployment: Store secrets in your platform's secret manager (Render Secrets, Fly.io Secrets, Vercel Env Vars), never in code or Docker images.
HTTP transport: /mcp has two built-in auth modes β GTM_MCP_HTTP_AUTH_TOKEN (one shared bearer token, identifies the deployment) and STYTCH_PROJECT_ID (per-user OAuth, each request resolved to that user's own Google grant). With neither set the transport refuses to start; GTM_MCP_HTTP_ALLOW_UNAUTHENTICATED=true overrides that for local development and binds loopback only.
Publish guard: Keep GTM_MCP_ENABLE_PUBLISH=false unless you explicitly intend to publish from an AI client. Publishing incorrect tags to production is the highest-risk operation.
Audit logs: The server logs all session events to stderr. Pipe to a logging service in production.
Development
bash
# Install dependencies
npm install
# TypeScript type check (no emit)
npm run typecheck
# Build
npm run build
# Watch mode
npm run build:watch
# Run dev server (stdio, with hot-reload)
npm run dev
# Run HTTP dev server
npm run dev:http
# Tests (run `npm run build` first β some suites test the compiled dist)
npm test# Smoke test: server boots and answers tools/list
npm run smoke -- --mcp dist/index.js
# Full-surface smoke test: invokes ALL registered tools with a sanitized,# credential-free env β every handler must respond cleanly (no crash/hang)
npm run smoke:all
# MCP Inspector (interactive tool debugging)
npm run inspector
Determines the next semantic version (MAJOR.MINOR.PATCH).
Updates CHANGELOG.md and bumps the version in package.json / package-lock.json.
Commits those files back to main with chore(release): x.y.z [skip ci] (the [skip ci] marker prevents an infinite release loop).
Creates a Git tag (vX.Y.Z) and a GitHub Release with auto-generated notes.
The workflow uses the built-in GITHUB_TOKEN and requires no additional secrets. npm publish is disabled β this package is distributed as a binary via the GitHub repo and releases, not via the npm registry.
feat!: drop support for Node.js 18
BREAKING CHANGE: minimum required Node version is now 20.
or:
code
refactor(auth): rename GOOGLE_REFRESH_TOKEN env var
BREAKING CHANGE: GOOGLE_REFRESH_TOKEN is now GTM_GOOGLE_REFRESH_TOKEN.
Update your .env file accordingly.
Dry run locally
To preview what the next release would look like without publishing:
"invalid_grant" or "Token has been expired or revoked"
Re-run npm run auth:google to refresh the token file
Or set GOOGLE_REFRESH_TOKEN directly in .env if you prefer env-managed tokens
If you're stuck in a loop where Google won't return a refresh_token, revoke prior access at myaccount.google.com/permissions and re-run the auth script
"Write operations are disabled"
Set GTM_MCP_ENABLE_WRITES=true in your .env
Restart the server / the desktop app
Stdio server shows no output
The stdio server intentionally writes nothing to stdout (stdout is the JSON-RPC channel)
Diagnostic output goes to stderr β check your terminal or Claude Desktop logs
Desktop app: Error: Electron uninstall on npm run dev
The Electron binary downloaded but never finished extracting - see the reliable
re-extract fix in apps/desktop/INSTALL.md
TypeScript errors on googleapis types
Run npm install to ensure all deps are installed
The googleapis package ships its own types β no @types/googleapis needed
TODOs / Known Limitations
workspace_resolve_conflict: The GTM API's resolve_conflict endpoint accepts a full entity body β the exact request body schema is complex. The current implementation passes through the user-supplied JSON; validate it against the entity type before calling.
containers_create: The usageContext enum values may differ slightly by GTM region/version. Refer to the GTM API docs for the latest allowed values.
Single-identity HTTP auth is a shared secret: GTM_MCP_HTTP_AUTH_TOKEN gates /mcp with one bearer token for every client, so it identifies the deployment, not the caller. For per-user identity, set STYTCH_PROJECT_ID to enable multi-user mode β see Security Notes.
HTTP sessions are in-memory: sessions live in the server process, so horizontal scaling requires sticky sessions. Fine for a single team instance; not yet built for multi-instance load balancing.
Single OAuth identity per deployment β single-identity mode only: without STYTCH_PROJECT_ID, all requests share one Google identity and therefore one Google API quota pool. Heavy multi-user load through one deployment will exhaust it; retries with backoff soften this but don't remove the quota ceiling. Multi-user mode sidesteps it β each member uses their own Google grant and quota.
Built by Samarth Analytics β Swapnil Jaykar & Sarthak Mandage
Install
Configuration
Environment variables
GOOGLE_OAUTH_CLIENT_IDrequired
Your Google OAuth 2.0 client ID (Desktop app type)
GOOGLE_OAUTH_CLIENT_SECRETrequiredsecret
Your Google OAuth 2.0 client secret
GTM_MCP_ENABLE_WRITES
Set to 'true' to allow create/update operations (default: read-only)
GTM_MCP_ENABLE_PUBLISH
Set to 'true' to allow publish operations (default: disabled)
GTM_MCP_ENABLE_DELETES
Set to 'true' to allow delete operations (default: disabled)