Query Analytics

Query Analytics is an MCP server that turns plain parameters into valid GA4 API requests, resolves human-readable date ranges, formats raw metric values, parses filter expressions, and aggregates response rows. No more digging through the GA4 reference docs mid-session.

Quick Start

Add this to your Claude Desktop or MCP client config:

{
  "mcpServers": {
    "query-analytics": {
      "url": "https://query-analytics-YOUR_HASH-uc.a.run.app/mcp"
    }
  }
}

Replace YOUR_HASH with the Cloud Run service URL from your deployment.

Before / After

Before: Hand-building a GA4 request body at 2am.

// What you used to write by hand:
{
  "dimensions": [{"name": "date"}, {"name": "country"}],
  "metrics": [{"name": "sessions"}, {"name": "bounceRate"}],
  "dateRanges": [{"startDate": "2026-03-06", "endDate": "2026-04-02"}],
  "limit": 1000,
  "orderBys": [{"metric": {"metricName": "sessions"}, "desc": true}]
}

After: One tool call.

build_ga4_query(
  metrics: ["sessions", "bounceRate"],
  dimensions: ["date", "country"],
  date_range: "last_28_days",
  order_by_metric: "sessions"
)

Output:

{
  "query": {
    "dimensions": [{"name": "date"}, {"name": "country"}],
    "metrics": [{"name": "sessions"}, {"name": "bounceRate"}],
    "dateRanges": [{"startDate": "2026-03-06", "endDate": "2026-04-02"}],
    "limit": 1000,
    "orderBys": [{"metric": {"metricName": "sessions"}, "desc": true}]
  },
  "resolvedDateRange": {
    "startDate": "2026-03-06",
    "endDate": "2026-04-02",
    "daysCount": 28
  }
}

Tools

Tool	What it does
build_ga4_query	Build a valid GA4 Data API runReport request body from plain parameters
get_date_range	Convert named periods (last_28_days, this_month, etc.) to start/end date strings
format_analytics_metric	Format raw numbers into human-readable strings (62.34%, 2m 14s, $1,234.00)
parse_filter_expression	Convert plain-text filter strings into GA4 filterExpression JSON
aggregate_rows	Roll up GA4 response rows by a dimension with metric summation and top-N

Who is this for?

• Analytics engineers who are tired of re-reading the GA4 API docs to remember the exact filterExpression schema.
• Product developers building dashboards who need clean, formatted metric values without writing formatting helpers from scratch.
• AI agents and automations that need to construct valid GA4 queries programmatically without hallucinating API structure.

Health Check

Both endpoints return the same JSON:

GET /
GET /health

{
  "status": "ok",
  "server": "query-analytics",
  "version": "1.0.0",
  "tools": 5
}

Use /health for Cloud Run liveness probes.

MCP Endpoint

POST /mcp

Handles all MCP protocol requests (tools/list, tools/call) via StreamableHTTP transport.

---

Built by Mastermind HQ

MIT License