samarth-analytics-mcp

# Samarth GTM MCP Server

[![CI](https://github.com/samarthanalytics-sj/samarth-analytics-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/samarthanalytics-sj/samarth-analytics-mcp/actions/workflows/ci.yml)

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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/`](./apps/portal/README.md). 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](#features)
2. [Quick Start](#quick-start)
3. [Friendly Google Auth Options](#friendly-google-auth-options)
4. [Google Cloud OAuth Setup](#google-cloud-oauth-setup)
5. [Service Account Limitations](#service-account-limitations)
6. [Environment Variables Reference](#environment-variables-reference)
7. [Guardrails](#guardrails)
8. [Available Tools](#available-tools)
9. [Claude Desktop Config](#claude-desktop-config)
10. [Cursor Config](#cursor-config)
11. [Claude Code Config](#claude-code-config)
12. [Cloud Deployment](#cloud-deployment)
13. [Security Notes](#security-notes)
14. [Development](#development)
15. [Releases](#releases)
16. [Troubleshooting](#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
- **Read-only GA4 coverage** — GA4 Admin tools (`ga4_*`) plus GA4 Data API reporting (`ga4_run_report`, `ga4_run_realtime_report`) for intent-vs-reality reconciliation, all under a single `analytics.readonly` scope
- **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:

```bash
# 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
```

In MCP client configs, use `"command": "npx", "args": ["-y", "samarth-gtm-mcp"]`.

### Install & Build (from source)

```bash
git clone https://github.com/samarthanalytics-sj/samarth-analytics-mcp.git
cd samarth-analytics-mcp
npm install
cp .env.example .env
# Edit .env — at minimum add GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
npm run build
```

### One-time OAuth Setup

The fastest way is the new browser-based onboarding script:

```bash
npm run auth:google
```

This will:
1. Start a tiny local callback server on `http://localhost:3001/oauth/callback`.
2. Open the Google authorization URL in your default browser (or print it if no browser is available).
3. Capture the redirect, exchange the code for tokens, and save them to `./.gtm-mcp-tokens.json` (mode `0600`, already in `.gitignore`).

You do **not** need to paste tokens into `.env` afterwards — the server reads them from the token file automatically. If you prefer to manage tokens by hand, the legacy paste-the-code helper is still available as `npm run oauth:setup`.

See [Friendly Google Auth Options](#friendly-google-auth-options) for the three supported setup paths (hosted, local dev, advanced).

### Verify it works

```bash
# Test stdio server starts (Ctrl+C to exit)
npm start

# Or use the MCP inspector
npm run inspector
```

---

## Friendly Google Auth Options

Google's Tag Manager API requires an OAuth-enabled Google Cloud project — **somebody has to own one**. There is no anonymous, key-free way to call the GTM API. What this MCP can do is hide that complexity behind a hosted backend, while still giving developers and teams the option to run everything themselves.

There are three supported paths. Pick the one that fits your situation.

### 1. Easiest — Samarth-hosted MCP (recommended for non-developers)

> Status: planned. This section documents the intended UX; the hosted endpoint is owned by Samarth Analytics and announced separately.

If you don't want to manage a Google Cloud project at all:

1. Point your MCP client at the Samarth-hosted endpoint (e.g. `https://mcp.samarthanalytics.com/mcp` via [`mcp-remote`](https://www.npmjs.com/package/mcp-remote)).
2. Sign in with Google in the browser when prompted.
3. Done — the hosted server uses the **Samarth-owned, Google-verified OAuth app**. The client secret lives only on the hosted backend; nothing sensitive ever ships to your machine.

Trade-off: you trust the Samarth-hosted backend to broker your Google tokens. It only ever requests the GTM scopes listed below.

### 2. Local developer — self-hosted with your own OAuth client

Best if you're comfortable in Google Cloud Console and want full control.

1. Create an **OAuth 2.0 Client ID** (type: **Desktop app** or **Web application**) in your own Google Cloud project. See [Google Cloud OAuth Setup](#google-cloud-oauth-setup) below for the exact steps.
2. Copy the client ID and secret into `.env`:
   ```env
   GOOGLE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret
   GOOGLE_OAUTH_REDIRECT_URI=http://localhost:3001/oauth/callback
   ```
   (The legacy `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` names still work.)
3. Run the browser-based onboarding flow:
   ```bash
   npm run auth:google
   ```
   It boots a local callback server, opens the consent screen, and writes tokens to `./.gtm-mcp-tokens.json` (gitignored, `0600`). The token file path is configurable via `GTM_MCP_TOKEN_FILE`.
4. Start the MCP server (`npm start` or via Claude Desktop / Cursor / Claude Code). Tokens are picked up from the file automatically — no need to paste anything into `.env`.

Trade-off: you maintain your own Google Cloud project and re-authorise every 7 days while the OAuth app is in "Testing" mode (or publish + verify it for permanent tokens).

### 3. Advanced / team — Samarth-owned OAuth on your own infra

Best for agencies and teams that want a hosted server with their own auth/IAM in front of it.

1. Deploy the MCP HTTP server (Render, Fly.io, Docker — see [Cloud Deployment](#cloud-deployment)).
2. Set the Samarth-owned (or your team-owned) OAuth client on the **server only**:
   ```env
   SAMARTH_GOOGLE_OAUTH_CLIENT_ID=public-client-id
   SAMARTH_GOOGLE_OAUTH_CLIENT_SECRET=secret-injected-from-secret-manager
   ```
   The secret **must** come from your platform's secret manager (Render Secrets, Fly Secrets, Vault, etc.). It is never committed to this repo and never shipped to client machines.
3. Front the `/mcp` endpoint with your own auth layer (API key header, IP allowlist, SSO proxy). The MCP server itself has no built-in user auth — see [Security Notes](#security-notes).
4. Users connect with their MCP client and never see Google Cloud Console.

Trade-off: you own the operational burden (Google API quota, OAuth app verification, secret rotation, user provisioning) in exchange for a friendly UX.

### Why we can't ship a "no-setup" client secret

Public OAuth clients distributed in source form (or pre-baked into an installer) are not secure: anyone can extract the secret and impersonate the app, leading to Google revoking it. This repo therefore:

- **Never** hardcodes a client secret.
- Treats `SAMARTH_GOOGLE_OAUTH_CLIENT_SECRET` as runtime-injected on the hosted backend only.
- Defaults the local flow (option 2) to your own OAuth client, which keeps the secret on your machine.

Scopes requested in every path:

```
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
```

These are the least-privilege scopes needed to cover the server's full tool surface. The final scope, `analytics.readonly`, powers both the **read-only GA4 Admin tools** (`ga4_*`) and the **read-only GA4 Data API reporting tools** (`ga4_run_report`, `ga4_run_realtime_report`) and grants no write access to Google Analytics. Read-only deployments can re-run `npm run auth:google` after r