mcp-ga4 1.0.1 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 drak-marketing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,102 +1,169 @@
 # mcp-ga4
 
-Ask Google Analytics 4 questions in plain English using Claude.
+MCP server for Google Analytics 4 -- run reports, realtime data, custom dimensions, and property management via Claude.
 
-## Quickstart (2 steps)
+## Features
 
-### 1. Setup
+- 9 tools covering reporting, realtime data, custom dimensions/metrics, data streams, and feedback
+- Two configuration modes: single-property (env vars) and multi-client (config.json)
+- Supports both service account and OAuth credentials
+- Relative date support (today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo)
+- Built on official Google SDKs with resilience patterns
+
+## Installation
 
 ```bash
-npx mcp-ga4-setup
+npm install mcp-ga4
 ```
 
-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
+Or clone the repository:
+
+```bash
+git clone https://github.com/drak-marketing/mcp-ga4.git
+cd mcp-ga4
+npm install
+npm run build
+```
 
-**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.
+## Configuration
 
-### 2. Configure Claude Code
+### Mode 1: Single Property (env vars)
 
-Copy the JSON snippet from the setup wizard into your Claude Code MCP config.
+Set environment variables to connect to a single GA4 property:
+
+```bash
+GA4_PROPERTY_ID=123456789
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+```
 
-The snippet looks like:
+For OAuth credentials instead of a service account:
+
+```bash
+GA4_PROPERTY_ID=123456789
+GA4_CREDENTIALS_FILE=/path/to/oauth-credentials.json
+```
+
+### Mode 2: Multi-Client (config.json)
+
+Create a `config.json` in the project root to map multiple GA4 properties to project directories. The server auto-detects which property to use based on the caller's working directory.
 
 ```json
 {
-  "ga4": {
-    "command": "npx",
-    "args": ["-y", "mcp-ga4"],
-    "env": {
-      "GA4_PROPERTY_ID": "YOUR_PROPERTY_ID",
-      "GOOGLE_APPLICATION_CREDENTIALS": "~/.config/mcp-ga4/credentials.json"
+  "credentials_file": "/path/to/oauth-credentials.json",
+  "clients": {
+    "client-a": {
+      "name": "Client A",
+      "folder": "/path/to/client-a/project",
+      "property_id": "123456789"
+    },
+    "client-b": {
+      "name": "Client B",
+      "folder": "/path/to/client-b/project",
+      "property_id": "987654321"
     }
   }
 }
 ```
 
-- **Claude Desktop (Mac):** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Claude Code CLI:** `.mcp.json` in your project directory
+## Usage
 
-That's it. No Python, no pip, no venv. Just `npx`.
+### Claude Code (.mcp.json)
 
-## Usage
+Single-property mode:
+
+```json
+{
+  "mcpServers": {
+    "ga4": {
+      "command": "npx",
+      "args": ["mcp-ga4"],
+      "env": {
+        "GA4_PROPERTY_ID": "123456789",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
+      }
+    }
+  }
+}
+```
+
+Multi-client mode:
 
-Once configured, just ask Claude questions about your analytics:
+```json
+{
+  "mcpServers": {
+    "ga4": {
+      "command": "node",
+      "args": ["/path/to/mcp-ga4/dist/index.js"]
+    }
+  }
+}
+```
 
-- "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"
+## Common Query Patterns
 
-## Feedback
+**Top pages:**
+dimensions=`pagePath`, metrics=`screenPageViews`, order_by=`screenPageViews`
 
-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.
+**Traffic sources:**
+dimensions=`sessionSource,sessionMedium`, metrics=`sessions,totalUsers`
 
-You can also say "send feedback" to Claude to report bugs or request features.
+**Daily trend:**
+dimensions=`date`, metrics=`sessions,totalUsers`
 
-## Troubleshooting
+**Campaign performance:**
+dimensions=`sessionCampaignName`, metrics=`sessions,conversions`
 
-**"No refresh token received"**
-Go to https://myaccount.google.com/permissions, remove "mcp-ga4", then re-run `npx mcp-ga4-setup`.
+**Device breakdown:**
+dimensions=`deviceCategory`, metrics=`sessions,totalUsers`
 
-**"Connection failed" / "Permission denied"**
-Your Google account may not have access to the GA4 property. Check your access at
-GA4 > Admin > Account Access Management.
+## Tools
 
-**Token expired**
-Re-run `npx mcp-ga4-setup` to refresh your credentials.
+| Tool | Description |
+|------|-------------|
+| `ga4_get_client_context` | Returns the active GA4 property ID and client name |
+| `ga4_run_report` | Run a standard GA4 report with dimensions, metrics, date range, and filters |
+| `ga4_realtime_report` | Query realtime data (last 30 minutes) |
+| `ga4_list_custom_dimensions` | List all custom dimensions for the property |
+| `ga4_create_custom_dimension` | Create a new custom dimension |
+| `ga4_list_custom_metrics` | List all custom metrics for the property |
+| `ga4_list_data_streams` | List web/app data streams and their measurement IDs |
+| `ga4_send_feedback` | Submit feedback on a query result |
+| `ga4_suggest_improvement` | Suggest a new query pattern or improvement |
 
-## Advanced: Multi-Property Setup
+## Date Formats
 
-For managing multiple GA4 properties, create `~/.config/mcp-ga4/config.json`:
+Use `YYYY-MM-DD` for absolute dates, or these relative shortcuts:
 
-```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"
-    }
-  }
-}
-```
+- `today`
+- `yesterday`
+- `7daysAgo`
+- `30daysAgo`
+- `90daysAgo`
+
+## Common Dimensions and Metrics
+
+**Dimensions:** date, dateHour, eventName, pagePath, pageTitle, sessionSource, sessionMedium, sessionCampaignName, country, city, deviceCategory, browser, operatingSystem, landingPage, pageReferrer, newVsReturning, firstUserSource, firstUserMedium, firstUserCampaignName
+
+**Metrics:** sessions, totalUsers, newUsers, activeUsers, screenPageViews, eventCount, conversions, engagedSessions, engagementRate, averageSessionDuration, bounceRate, sessionsPerUser, screenPageViewsPerSession, userEngagementDuration
+
+## Data Freshness
+
+- Standard reports: 24-48 hour delay
+- Realtime reports: last 30 minutes only
+
+## Architecture
+
+Built on:
+
+- `@google-analytics/data` -- GA4 Data API for reports
+- `@google-analytics/admin` -- GA4 Admin API for property management
+- `cockatiel` -- resilience (retry, circuit breaker)
+- `pino` -- structured logging
 
 ## License
 
 MIT
+
+## Author
+
+Built by Mark Harnett / [drak-marketing](https://github.com/drak-marketing)

package/config.example.json

@@ -0,0 +1,10 @@
+{
+  "credentials_file": "/path/to/credentials.json",
+  "clients": {
+    "my-site": {
+      "name": "My Website",
+      "folder": "/path/to/project",
+      "property_id": "123456789"
+    }
+  }
+}

package/dist/build-info.json

@@ -0,0 +1 @@
+{"sha":"38406d3","builtAt":"2026-04-03T23:26:52.380Z"}

package/dist/errors.d.ts

@@ -1,15 +1,12 @@
-/**
- * Typed errors and classification for GA4 API calls.
- */
-export declare class GA4AuthError extends Error {
+export declare class Ga4AuthError extends Error {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
 }
-export declare class GA4RateLimitError extends Error {
+export declare class Ga4RateLimitError extends Error {
     readonly retryAfterMs: number;
     constructor(retryAfterMs: number, cause?: unknown);
 }
-export declare class GA4ServiceError extends Error {
+export declare class Ga4ServiceError extends Error {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
 }

package/dist/errors.js

@@ -1,59 +1,42 @@
-/**
- * Typed errors and classification for GA4 API calls.
- */
-export class GA4AuthError extends Error {
+export class Ga4AuthError extends Error {
     cause;
     constructor(message, cause) {
         super(message);
         this.cause = cause;
-        this.name = "GA4AuthError";
+        this.name = "Ga4AuthError";
     }
 }
-export class GA4RateLimitError extends Error {
+export class Ga4RateLimitError extends Error {
     retryAfterMs;
     constructor(retryAfterMs, cause) {
         super(`Rate limited, retry after ${retryAfterMs}ms`);
-        this.name = "GA4RateLimitError";
         this.retryAfterMs = retryAfterMs;
+        this.name = "Ga4RateLimitError";
         this.cause = cause;
     }
 }
-export class GA4ServiceError extends Error {
+export class Ga4ServiceError extends Error {
     cause;
     constructor(message, cause) {
         super(message);
         this.cause = cause;
-        this.name = "GA4ServiceError";
+        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);
+    const message = error?.message || String(error);
+    const code = error?.code || error?.status;
+    if (code === 401 || code === 403 || code === 7 || code === 16 ||
+        message.includes("PERMISSION_DENIED") || message.includes("UNAUTHENTICATED") ||
+        message.includes("invalid_grant")) {
+        return new Ga4AuthError(`Auth failed: ${message}. Check credentials.`, error);
     }
-    // Rate limiting
-    if (status === 429 || message.includes("RESOURCE_EXHAUSTED")) {
-        const retryMs = 60_000;
-        return new GA4RateLimitError(retryMs, error);
+    if (code === 429 || code === 8 || message.includes("RESOURCE_EXHAUSTED") || message.includes("rateLimitExceeded")) {
+        return new Ga4RateLimitError(60_000, 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;
+    if (code >= 500 || code === 13 || code === 14 ||
+        message.includes("INTERNAL") || message.includes("UNAVAILABLE")) {
+        return new Ga4ServiceError(`GA4 API server error: ${message}`, error);
     }
     return error;
 }

package/dist/index.d.ts

@@ -1,9 +1,2 @@
 #!/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 {};