mcp-ga4 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# mcp-ga4
+
+Ask Google Analytics 4 questions in plain English using Claude.
+
+## Quickstart (2 steps)
+
+### 1. Setup
+
+```bash
+npx mcp-ga4-setup
+```
+
+This will:
+- Ask for your GA4 property ID (find it in GA4 > Admin > Property Details)
+- Open your browser to sign in with Google
+- Verify the connection works
+- Generate the Claude Code configuration snippet
+
+**Note:** You may see a "Google hasn't verified this app" warning during sign-in.
+Click **Advanced** then **Go to mcp-ga4 (unsafe)** to continue. This is safe --
+the app only requests read-only access to your analytics data.
+
+### 2. Configure Claude Code
+
+Copy the JSON snippet from the setup wizard into your Claude Code MCP config.
+
+The snippet looks like:
+
+```json
+{
+  "ga4": {
+    "command": "npx",
+    "args": ["-y", "mcp-ga4"],
+    "env": {
+      "GA4_PROPERTY_ID": "YOUR_PROPERTY_ID",
+      "GOOGLE_APPLICATION_CREDENTIALS": "~/.config/mcp-ga4/credentials.json"
+    }
+  }
+}
+```
+
+- **Claude Desktop (Mac):** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Claude Code CLI:** `.mcp.json` in your project directory
+
+That's it. No Python, no pip, no venv. Just `npx`.
+
+## Usage
+
+Once configured, just ask Claude questions about your analytics:
+
+- "What were my top 10 pages last week?"
+- "Show me traffic by source for the past 30 days"
+- "What's my bounce rate trend this month?"
+- "Which campaigns drove the most conversions?"
+- "What devices are my users on?"
+- "Show me real-time active users"
+
+## Feedback
+
+If a query doesn't return what you expected, tell Claude! It will log the
+pattern using the built-in `ga4_suggest_improvement` tool so the tool can
+be improved for everyone.
+
+You can also say "send feedback" to Claude to report bugs or request features.
+
+## Troubleshooting
+
+**"No refresh token received"**
+Go to https://myaccount.google.com/permissions, remove "mcp-ga4", then re-run `npx mcp-ga4-setup`.
+
+**"Connection failed" / "Permission denied"**
+Your Google account may not have access to the GA4 property. Check your access at
+GA4 > Admin > Account Access Management.
+
+**"OAuth client credentials not found"**
+The setup needs OAuth client credentials. Set `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`
+environment variables, or on macOS store them in Keychain (the setup will guide you).
+
+**Token expired**
+Re-run `npx mcp-ga4-setup` to refresh your credentials.
+
+## Advanced: Multi-Property Setup
+
+For managing multiple GA4 properties, create `~/.config/mcp-ga4/config.json`:
+
+```json
+{
+  "credentials_file": "~/.config/mcp-ga4/credentials.json",
+  "clients": {
+    "my-site": {
+      "name": "My Website",
+      "folder": "/path/to/project",
+      "property_id": "123456789"
+    },
+    "other-site": {
+      "name": "Other Site",
+      "folder": "/path/to/other",
+      "property_id": "987654321"
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,34 @@
+/**
+ * OAuth credential loading and token refresh for GA4 APIs.
+ *
+ * Supports two credential types:
+ * 1. authorized_user -- OAuth with refresh token (from mcp-ga4-setup)
+ * 2. service_account -- Service account JSON key file
+ */
+interface AuthorizedUserCreds {
+    type: "authorized_user";
+    client_id: string;
+    client_secret: string;
+    refresh_token: string;
+}
+interface ServiceAccountCreds {
+    type: "service_account";
+    client_email: string;
+    private_key: string;
+    token_uri: string;
+}
+type CredentialFile = AuthorizedUserCreds | ServiceAccountCreds;
+export declare function loadCredentials(credentialsFile: string): CredentialFile;
+/**
+ * Get a valid access token, refreshing if needed.
+ */
+export declare function getAccessToken(credentialsFile: string): Promise<string>;
+/**
+ * Validate credentials exist and are readable. Returns credential type info.
+ */
+export declare function validateCredentials(credentialsFile: string): {
+    valid: boolean;
+    type?: string;
+    error?: string;
+};
+export {};

package/dist/auth.js

@@ -0,0 +1,130 @@
+/**
+ * OAuth credential loading and token refresh for GA4 APIs.
+ *
+ * Supports two credential types:
+ * 1. authorized_user -- OAuth with refresh token (from mcp-ga4-setup)
+ * 2. service_account -- Service account JSON key file
+ */
+import { readFileSync } from "fs";
+import { logger } from "./resilience.js";
+let cachedAccessToken = null;
+let tokenExpiry = 0;
+let cachedCreds = null;
+export function loadCredentials(credentialsFile) {
+    if (cachedCreds)
+        return cachedCreds;
+    const raw = readFileSync(credentialsFile, "utf-8");
+    cachedCreds = JSON.parse(raw);
+    return cachedCreds;
+}
+/**
+ * Get a valid access token, refreshing if needed.
+ */
+export async function getAccessToken(credentialsFile) {
+    if (cachedAccessToken && Date.now() < tokenExpiry) {
+        return cachedAccessToken;
+    }
+    const creds = loadCredentials(credentialsFile);
+    if (creds.type === "authorized_user") {
+        return refreshOAuthToken(creds);
+    }
+    else if (creds.type === "service_account") {
+        return getServiceAccountToken(creds);
+    }
+    throw new Error(`Unsupported credential type: ${creds.type}`);
+}
+async function refreshOAuthToken(creds) {
+    const params = new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: creds.client_id,
+        client_secret: creds.client_secret,
+        refresh_token: creds.refresh_token,
+    });
+    const resp = await fetch("https://oauth2.googleapis.com/token", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: params.toString(),
+    });
+    if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`OAuth token refresh failed (${resp.status}): ${text}`);
+    }
+    const data = (await resp.json());
+    cachedAccessToken = data.access_token;
+    tokenExpiry = Date.now() + (data.expires_in - 60) * 1000;
+    logger.debug("OAuth token refreshed");
+    return cachedAccessToken;
+}
+async function getServiceAccountToken(creds) {
+    // Build JWT for service account
+    const now = Math.floor(Date.now() / 1000);
+    const header = { alg: "RS256", typ: "JWT" };
+    const payload = {
+        iss: creds.client_email,
+        scope: "https://www.googleapis.com/auth/analytics.readonly https://www.googleapis.com/auth/analytics.edit",
+        aud: creds.token_uri || "https://oauth2.googleapis.com/token",
+        iat: now,
+        exp: now + 3600,
+    };
+    const { createSign } = await import("crypto");
+    const encode = (obj) => Buffer.from(JSON.stringify(obj)).toString("base64url");
+    const unsigned = `${encode(header)}.${encode(payload)}`;
+    const sign = createSign("RSA-SHA256");
+    sign.update(unsigned);
+    const signature = sign.sign(creds.private_key, "base64url");
+    const jwt = `${unsigned}.${signature}`;
+    const params = new URLSearchParams({
+        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+        assertion: jwt,
+    });
+    const resp = await fetch(creds.token_uri || "https://oauth2.googleapis.com/token", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: params.toString(),
+    });
+    if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`Service account token exchange failed (${resp.status}): ${text}`);
+    }
+    const data = (await resp.json());
+    cachedAccessToken = data.access_token;
+    tokenExpiry = Date.now() + (data.expires_in - 60) * 1000;
+    logger.debug({ serviceAccount: creds.client_email }, "Service account token obtained");
+    return cachedAccessToken;
+}
+/**
+ * Validate credentials exist and are readable. Returns credential type info.
+ */
+export function validateCredentials(credentialsFile) {
+    if (!credentialsFile) {
+        return {
+            valid: false,
+            error: "No credentials file specified (GOOGLE_APPLICATION_CREDENTIALS)",
+        };
+    }
+    try {
+        const creds = loadCredentials(credentialsFile);
+        if (creds.type === "authorized_user") {
+            if (!creds.refresh_token) {
+                return { valid: false, error: "Missing refresh_token in credentials" };
+            }
+            return { valid: true, type: "authorized_user" };
+        }
+        else if (creds.type === "service_account") {
+            if (!creds.private_key || !creds.client_email) {
+                return {
+                    valid: false,
+                    error: "Missing private_key or client_email in service account",
+                };
+            }
+            return {
+                valid: true,
+                type: `service_account (${creds.client_email})`,
+            };
+        }
+        return { valid: false, error: `Unknown credential type: ${creds.type}` };
+    }
+    catch (err) {
+        return { valid: false, error: err.message };
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Typed errors and classification for GA4 API calls.
+ */
+export declare class GA4AuthError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare class GA4RateLimitError extends Error {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number, cause?: unknown);
+}
+export declare class GA4ServiceError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare function classifyError(error: any): Error;

package/dist/errors.js

@@ -0,0 +1,59 @@
+/**
+ * Typed errors and classification for GA4 API calls.
+ */
+export class GA4AuthError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "GA4AuthError";
+    }
+}
+export class GA4RateLimitError extends Error {
+    retryAfterMs;
+    constructor(retryAfterMs, cause) {
+        super(`Rate limited, retry after ${retryAfterMs}ms`);
+        this.name = "GA4RateLimitError";
+        this.retryAfterMs = retryAfterMs;
+        this.cause = cause;
+    }
+}
+export class GA4ServiceError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "GA4ServiceError";
+    }
+}
+export function classifyError(error) {
+    const message = typeof error?.message === "string" ? error.message : String(error);
+    const status = error?.status || error?.code;
+    // Auth failures
+    if (status === 401 ||
+        status === 403 ||
+        message.includes("invalid_grant") ||
+        message.includes("Token has been expired") ||
+        message.includes("refresh token") ||
+        message.includes("UNAUTHENTICATED") ||
+        message.includes("PERMISSION_DENIED")) {
+        return new GA4AuthError(`Auth failed: ${message}. Re-run mcp-ga4-setup to refresh credentials.`, error);
+    }
+    // Rate limiting
+    if (status === 429 || message.includes("RESOURCE_EXHAUSTED")) {
+        const retryMs = 60_000;
+        return new GA4RateLimitError(retryMs, error);
+    }
+    // Server errors
+    if ((typeof status === "number" && status >= 500) ||
+        message.includes("INTERNAL")) {
+        return new GA4ServiceError(`GA4 API server error: ${message}`, error);
+    }
+    if (!(error instanceof Error)) {
+        const wrapped = new Error(message);
+        wrapped.name = "GA4Error";
+        wrapped.cause = error;
+        return wrapped;
+    }
+    return error;
+}

package/dist/ga4.d.ts

@@ -0,0 +1,23 @@
+/**
+ * GA4 REST API client -- Data API + Admin API.
+ *
+ * Uses direct REST calls instead of heavy client libraries
+ * to keep the package lightweight for distribution.
+ */
+export declare class GA4Manager {
+    private credentialsFile;
+    constructor(credentialsFile: string);
+    private request;
+    runReport(propertyId: string, dimensions: string[], metrics: string[], startDate: string, endDate: string, dimensionFilter?: {
+        field: string;
+        value: string;
+    }, limit?: number, orderBy?: string): Promise<any>;
+    runRealtimeReport(propertyId: string, dimensions: string[], metrics: string[], dimensionFilter?: {
+        field: string;
+        value: string;
+    }): Promise<any>;
+    listDataStreams(propertyId: string): Promise<any>;
+    listCustomDimensions(propertyId: string): Promise<any>;
+    createCustomDimension(propertyId: string, parameterName: string, displayName: string, scope: string, description: string): Promise<any>;
+    listCustomMetrics(propertyId: string): Promise<any>;
+}

package/dist/ga4.js

@@ -0,0 +1,151 @@
+/**
+ * GA4 REST API client -- Data API + Admin API.
+ *
+ * Uses direct REST calls instead of heavy client libraries
+ * to keep the package lightweight for distribution.
+ */
+import { getAccessToken } from "./auth.js";
+import { withResilience, safeResponse } from "./resilience.js";
+import { classifyError } from "./errors.js";
+const DATA_API = "https://analyticsdata.googleapis.com/v1beta";
+const ADMIN_API = "https://analyticsadmin.googleapis.com/v1beta";
+export class GA4Manager {
+    credentialsFile;
+    constructor(credentialsFile) {
+        this.credentialsFile = credentialsFile;
+    }
+    async request(url, method = "GET", body) {
+        const token = await getAccessToken(this.credentialsFile);
+        const options = {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+        };
+        if (body) {
+            options.body = JSON.stringify(body);
+        }
+        const resp = await fetch(url, options);
+        if (!resp.ok) {
+            const text = await resp.text();
+            const err = new Error(`GA4 API ${resp.status}: ${text}`);
+            err.status = resp.status;
+            throw classifyError(err);
+        }
+        return resp.json();
+    }
+    // ============================================
+    // DATA API
+    // ============================================
+    async runReport(propertyId, dimensions, metrics, startDate, endDate, dimensionFilter, limit = 100, orderBy) {
+        const body = {
+            dimensions: dimensions.map((d) => ({ name: d })),
+            metrics: metrics.map((m) => ({ name: m })),
+            dateRanges: [{ startDate, endDate }],
+            limit,
+        };
+        if (dimensionFilter) {
+            body.dimensionFilter = {
+                filter: {
+                    fieldName: dimensionFilter.field,
+                    stringFilter: { value: dimensionFilter.value },
+                },
+            };
+        }
+        if (orderBy) {
+            body.orderBys = [
+                { metric: { metricName: orderBy }, desc: true },
+            ];
+        }
+        const data = await withResilience(() => this.request(`${DATA_API}/properties/${propertyId}:runReport`, "POST", body), "runReport");
+        const rows = parseReportRows(data);
+        return safeResponse({ rows, row_count: rows.length, date_range: `${startDate} to ${endDate}` }, "runReport");
+    }
+    async runRealtimeReport(propertyId, dimensions, metrics, dimensionFilter) {
+        const body = {
+            dimensions: dimensions.map((d) => ({ name: d })),
+            metrics: metrics.map((m) => ({ name: m })),
+        };
+        if (dimensionFilter) {
+            body.dimensionFilter = {
+                filter: {
+                    fieldName: dimensionFilter.field,
+                    stringFilter: { value: dimensionFilter.value },
+                },
+            };
+        }
+        const data = await withResilience(() => this.request(`${DATA_API}/properties/${propertyId}:runRealtimeReport`, "POST", body), "runRealtimeReport");
+        const rows = parseReportRows(data);
+        return safeResponse({ rows, row_count: rows.length }, "runRealtimeReport");
+    }
+    // ============================================
+    // ADMIN API
+    // ============================================
+    async listDataStreams(propertyId) {
+        const data = await withResilience(() => this.request(`${ADMIN_API}/properties/${propertyId}/dataStreams`), "listDataStreams");
+        const streams = (data.dataStreams || []).map((s) => ({
+            name: s.displayName,
+            type: s.type,
+            ...(s.webStreamData && {
+                measurement_id: s.webStreamData.measurementId,
+                default_uri: s.webStreamData.defaultUri,
+            }),
+        }));
+        return { data_streams: streams, count: streams.length };
+    }
+    async listCustomDimensions(propertyId) {
+        const data = await withResilience(() => this.request(`${ADMIN_API}/properties/${propertyId}/customDimensions`), "listCustomDimensions");
+        const dims = (data.customDimensions || []).map((d) => ({
+            name: d.displayName,
+            parameter_name: d.parameterName,
+            scope: d.scope,
+            description: d.description || "",
+        }));
+        return { custom_dimensions: dims, count: dims.length };
+    }
+    async createCustomDimension(propertyId, parameterName, displayName, scope, description) {
+        const body = {
+            parameterName,
+            displayName,
+            scope: scope.toUpperCase() === "USER" ? "USER_SCOPE" : "EVENT_SCOPE",
+            description,
+        };
+        const result = await withResilience(() => this.request(`${ADMIN_API}/properties/${propertyId}/customDimensions`, "POST", body), "createCustomDimension");
+        return {
+            created: result.displayName,
+            parameter_name: result.parameterName,
+            scope: result.scope,
+        };
+    }
+    async listCustomMetrics(propertyId) {
+        const data = await withResilience(() => this.request(`${ADMIN_API}/properties/${propertyId}/customMetrics`), "listCustomMetrics");
+        const metrics = (data.customMetrics || []).map((m) => ({
+            name: m.displayName,
+            parameter_name: m.parameterName,
+            scope: m.scope,
+            measurement_unit: m.measurementUnit,
+            description: m.description || "",
+        }));
+        return { custom_metrics: metrics, count: metrics.length };
+    }
+}
+// ============================================
+// HELPERS
+// ============================================
+function parseReportRows(data) {
+    if (!data.rows)
+        return [];
+    const dimHeaders = (data.dimensionHeaders || []).map((h) => h.name);
+    const metHeaders = (data.metricHeaders || []).map((h) => h.name);
+    return data.rows.map((row) => {
+        const r = {};
+        (row.dimensionValues || []).forEach((v, i) => {
+            r[dimHeaders[i]] = v.value;
+        });
+        (row.metricValues || []).forEach((v, i) => {
+            r[metHeaders[i]] = v.value;
+        });
+        return r;
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * mcp-ga4 -- MCP server for querying Google Analytics 4 via natural language.
+ *
+ * Supports two config modes:
+ * 1. Single-property (env vars): GA4_PROPERTY_ID + GOOGLE_APPLICATION_CREDENTIALS
+ * 2. Multi-client (config.json): MCP_GA4_CONFIG or ~/.config/mcp-ga4/config.json
+ */
+export {};