Analytics MCP

One-click GA4 + GTM analytics automation for developers, agencies, and AI agents.

Automate Google Analytics 4 and Google Tag Manager setup, apply opinionated tracking blueprints, monitor health, and manage everything via CLI, REST API, MCP tools, or Web UI.

Features • Quickstart • Screenshots • CLI • MCP • API

---

Features

Feature	Description
GA4 Automation	Create properties, web data streams, optional BigQuery export
GTM Automation	Containers, GA4 config tags, event tags, publish & snippets
Tracking Blueprints	SaaS, ecommerce, content, Web Vitals presets with dataLayer specs
Site Analyzer	Playwright-based crawling — discover pages, group by business intent, identify tracking opportunities
GA4 Data Querying	Schema discovery + natural language queries (like surendranb/google-analytics-mcp)
Consent Presets	none, basic, and advanced consent-gated triggers
Multi-Environment	Separate dev/stage/prod configurations
Governance	Audit log, GTM diff, rollback
Health Monitoring	Scheduled checks, webhook/email alerts, time-series charts
MCP Integration	10 tools for Claude, Gemini, and other MCP clients
Web Dashboard	Create, monitor, and manage sites visually with charts
Security	KMS/Secrets Manager support (AWS, GCP, Azure)
Reliability	Automatic retry with exponential backoff for API calls

---

Competitive Landscape

How MCP Metrics Compares

Project	Stars	What They Do	What MCP Metrics Adds
jtrackingai/analytics-tracking-automation	131	AI-powered GA4 + GTM event tracking with site analysis	Full property/container lifecycle + governance + health monitoring + integrated dashboard
surendranb/google-analytics-mcp	222	GA4 data querying for AI agents (read-only)	Write/setup side — create properties, GTM containers, blueprints via MCP
owntag/gtm-cli	~50	CLI for GTM API operations	Full platform — GA4 + GTM + blueprints + UI + health + governance
google-marketing-solutions/web-vitals-gtm-template	42	GTM template for Core Web Vitals	Integrated blueprint — Web Vitals as first-class tracking preset

Key Differentiators

vs jtrackingai/analytics-tracking-automation:

• We have full GA4 property creation (they focus on event tracking within existing properties)
• We have governance (audit logs, GTM diff, rollback)
• We have health monitoring with time-series charts
• We have integrated web dashboard (not just CLI skill)
• We have consent management and cross-domain tracking

vs surendranb/google-analytics-mcp:

• They are read/query only — GA4 data access for analysis
• We are write/setup focused — create and configure GA4/GTM from scratch
• Complementary pairing: Use MCP Metrics to set up tracking, use their server to query results

vs owntag/gtm-cli:

• They provide low-level GTM API access
• We provide high-level opinionated platform — one command for full setup
• We add GA4 integration, blueprints, health monitoring, web UI

vs Web Vitals GTM Template:

• They provide a GTM template gallery entry
• We provide Web Vitals as a blueprint integrated into the full automation workflow
• We include attribution data and debugging support in the dataLayer

---

Quickstart

Prerequisites

• Docker & Docker Compose
• Python 3.11+ (for local dev)
• Google Cloud service account with GA4 Admin, GTM, and (optional) BigQuery permissions

1. Clone and configure

git clone https://github.com/abhishekshankar/MCP-Metrics.git
cd MCP-Metrics
cp config/env.example .env
# Edit .env with your GTM account ID and credentials path

2. Start services

docker compose up -d

API available at http://localhost:8000 — health check:

curl http://localhost:8000/health

3. Create your first site

pip install -e ".[dev]"
analytics-mcp create \
  --domain example.com \
  --name "Example Site" \
  --env prod \
  --blueprint saas \
  --pretty

4. Web UI

cd web-ui && npm install && npm run dev

Open http://localhost:5173

---

Screenshots

Dashboard

List all your analytics setups with health status at a glance.

┌─────────────────────────────────────────────────────────────┐
│  Sites Dashboard                                            │
├──────────────┬──────────┬─────┬──────────┬────────┬────────┤
│ Domain       │ Name     │ Env │ Blueprint│ GTM    │ Status │
├──────────────┼──────────┼─────┼──────────┼────────┼────────┤
│ example.com  │ Example  │ prod│ saas     │ GTM-ABC│ active │
│ shop.com     │ Shop     │ prod│ ecommerce│ GTM-DEF│ active │
│ blog.com     │ Blog     │ prod│ content  │ GTM-GHI│ active │
└──────────────┴──────────┴─────┴──────────┴────────┴────────┘

Site Detail with Health Charts

View detailed health metrics with time-series charts showing events, sessions, and conversions over time.

┌─────────────────────────────────────────────────────────────┐
│  example.com · prod                                         │
├─────────────────────────────────────────────────────────────┤
│  G-XXXXXXXX  │  GTM-XXXX  │  saas  │  healthy              │
├─────────────────────────────────────────────────────────────┤
│  Health Metrics (24h)                                         │
│  ┌─────────────────────────────────────────────────────────┐│
│  │  Events: 1,500  │  Sessions: 800  │  Conversions: 45  ││
│  └─────────────────────────────────────────────────────────┘│
│                                                             │
│  Health Trends (30 Days)                                    │
│  ═══════════════════════════════════════════════════════    │
│  ║  Chart: Events & Sessions over time                    ║    │
│  ║  Chart: Conversions bar chart                           ║    │
│  ═══════════════════════════════════════════════════════    │
│                                                             │
│  GTM Configuration Diff                                     │
│  ├─ Tags: +3 added, -1 removed                              │
│  ├─ Triggers: +2 added                                     │
│  └─ Variables: no changes                                  │
└─────────────────────────────────────────────────────────────┘

Blueprint Editor

View, edit, and create custom tracking blueprints with live validation.

┌─────────────────────────────────────────────────────────────┐
│  Blueprint Editor                                           │
│  [saas] [ecommerce] [content] [+ New Blueprint]             │
├─────────────────────────────────────────────────────────────┤
│  name: saas                                                 │
│  description: SaaS product site tracking                   │
│  events:                                                    │
│    - signup_started                                         │
│    - signup_completed                                       │
│    - trial_started                                          │
│    - pricing_view                                           │
│                                                             │
│  [Apply to Site]  [Save Changes]                            │
└─────────────────────────────────────────────────────────────┘

---

CLI Commands

Command	Description
analytics-mcp create	Full GA4 + GTM + blueprint setup
analytics-mcp status	Get site status
analytics-mcp list	List all sites
analytics-mcp apply-blueprint	Apply/update blueprint
analytics-mcp health	Run health check
analytics-mcp rollback	Rollback GTM version
analytics-mcp describe	Human-readable setup summary

---

MCP Client Setup

Claude Desktop

Copy config/mcp-claude.example.json into your Claude Desktop MCP config:

{
  "mcpServers": {
    "analytics": {
      "command": "python",
      "args": ["/path/to/analytics_mcp_mcp_server.py"],
      "env": {
        "DATABASE_URL": "postgresql://..."
      }
    }
  }
}

Available MCP Tools

Tool	Description
Setup & Management
create_analytics_setup	Create GA4 + GTM setup for a new site
get_analytics_status	Get current status of a site's analytics
apply_tracking_blueprint	Apply a tracking blueprint to a site
describe_analytics_setup	Get human-readable description of setup
get_health_status	Get health status with metrics
GA4 Data & Schema
search_ga4_schema	Search dimensions/metrics by keyword (like surendranb/google-analytics-mcp)
list_dimension_categories	List all GA4 dimension categories
list_metric_categories	List all GA4 metric categories
get_dimensions_by_category	Get dimensions organized by category
get_metrics_by_category	Get metrics organized by category
query_ga4_data	Query GA4 data with intelligent defaults and row estimation
Verification & Analysis
verify_gtm_preview	Test GTM Preview mode — verify tags fire before publishing
analyze_site_structure	Crawl site to discover pages and tracking opportunities

---

REST API

Core Endpoints

Method	Endpoint	Description
GET	/health	Service health
POST	/sites	Create site
GET	/sites	List sites
GET	/sites/:domain	Site status
POST	/sites/:domain/blueprint	Apply blueprint
GET	/sites/:domain/health	Health check
GET	/sites/:domain/health/history	Health history (charts data)
GET	/sites/:domain/versions	Blueprint version history
GET	/sites/:domain/diff	GTM config diff
POST	/sites/:domain/rollback	Rollback
GET	/audit	Audit log
POST	/blueprints/:name	Save custom blueprint
POST	/sites/:domain/analyze	Site analyzer — crawl and analyze site structure (Playwright)
POST	/sites/:domain/verify-preview	Preview verification — test GTM tags before publishing

OpenAPI docs: http://localhost:8000/docs

Authentication

Pass X-API-Key header with admin or readonly key (configured in .env):

curl -H "X-API-Key: admin-key-change-me" http://localhost:8000/sites

---

Architecture

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│    CLI      │  │   Web UI    │  │  MCP Client │
│   (Typer)   │  │  (React)    │  │   (FastMCP) │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │
       └────────────────┼────────────────┘
                        │
              ┌─────────▼──────────┐
              │   FastAPI REST     │
              │  + MCP Server      │
              └─────────┬──────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
┌───────▼───────┐ ┌─────▼─────┐ ┌──────▼──────┐
│  GA4Service   │ │ GTMService│ │HealthService│
│  (w/ retry)   │ │ (w/ retry)│ │(w/ scheduler)│
└───────┬───────┘ └─────┬─────┘ └──────┬──────┘
        │               │              │
        └───────────────┼──────────────┘
                        │
        ┌───────────────▼───────────────┐
        │    Google APIs (GA4, GTM, BQ) │
        └───────────────────────────────┘
                        │
               ┌────────▼────────┐
               │   PostgreSQL    │
               │  (Sites, Audit)  │
               └─────────────────┘

---

Security Features

KMS/Secrets Manager Support

Store Google service account credentials securely:

# AWS Secrets Manager
KMS_PROVIDER=aws
AWS_SECRET_NAME=analytics-mcp/google-credentials

# GCP Secret Manager
KMS_PROVIDER=gcp
GOOGLE_CLOUD_PROJECT=your-project

# Azure Key Vault
KMS_PROVIDER=azure
AZURE_KEY_VAULT_URL=https://your-vault.vault.azure.net/
AZURE_SECRET_NAME=google-credentials

API Authentication

• Admin and read-only API keys
• Role-based access control
• Audit logging of all operations

---

Development

# Install dependencies
pip install -e ".[dev]"

# Install Playwright browsers (required for site analyzer and preview verification)
playwright install chromium

# Run tests
MOCK_GOOGLE_APIS=true pytest backend/tests -v

# Run API locally
DATABASE_URL=postgresql://analytics:analytics@localhost:5432/analytics_mcp \
MOCK_GOOGLE_APIS=true \
PYTHONPATH=backend/src uvicorn main:app --reload

# Run migrations
alembic -c backend/alembic.ini upgrade head

# Web UI development
cd web-ui && npm install && npm run dev

---

Configuration

Environment Variables

Variable	Description	Default
MOCK_GOOGLE_APIS	Use mock Google APIs (no real credentials needed)	true
GOOGLE_APPLICATION_CREDENTIALS	Path to service account JSON	-
GTM_ACCOUNT_ID	GTM account ID	1234567
KMS_PROVIDER	Secrets manager (aws/gcp/azure)	-
API_RETRY_ATTEMPTS	Number of retry attempts for API calls	3
HEALTH_CHECK_INTERVAL_MINUTES	Health check scheduler interval	60

See config/env.example for full configuration options.

---

Mock Mode

Set MOCK_GOOGLE_APIS=true (default in docker-compose) to run without real Google credentials. All GA4/GTM operations use in-memory mocks — ideal for development and CI.

---

Contributing

Contributions welcome! Please read our contributing guidelines (coming soon).

---

License

MIT — see LICENSE