Samarth Analytics MCP

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.	Quick Start and Google Cloud OAuth Setup
Self-hosted	The MCP server, the web-audit server and the capture worker as one docker-compose stack behind your own token.	docs/SELF_HOSTING_DOCKER.md and Cloud Deployment

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.

---

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:

   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:

   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

Variable	Default	Description
GOOGLE_OAUTH_CLIENT_ID	—	OAuth client ID (preferred). Falls back to GOOGLE_CLIENT_ID.
GOOGLE_OAUTH_CLIENT_SECRET	—	OAuth client secret (preferred). Falls back to GOOGLE_CLIENT_SECRET.
GOOGLE_OAUTH_REDIRECT_URI	http://localhost:3001/oauth/callback	OAuth redirect URI. Falls back to GOOGLE_REDIRECT_URI.
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_REDIRECT_URI	—	Legacy names, still supported.
SAMARTH_GOOGLE_OAUTH_CLIENT_ID	—	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):

GTM_MCP_ENABLE_WRITES=false
GTM_MCP_ENABLE_PUBLISH=false
GTM_MCP_ENABLE_DELETES=false

Development workspace edits (no publishing):

GTM_MCP_ENABLE_WRITES=true
GTM_MCP_ENABLE_PUBLISH=false
GTM_MCP_ENABLE_DELETES=false

Full access (use with care):

GTM_MCP_ENABLE_WRITES=true
GTM_MCP_ENABLE_PUBLISH=true
GTM_MCP_ENABLE_DELETES=true

---

Available Tools

Accounts

Tool	Description
accounts_list	List all accessible GTM accounts
accounts_get	Get a specific account

Containers

Tool	Description
containers_list	List containers in an account (auto-paginated)
containers_get	Get a specific container
containers_create	✏️ Create a new container
containers_snippet	Get the GTM installation snippet for a container
containers_lookup	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 same https://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