mcp-ga4

An MCP (Model Context Protocol) server that gives AI agents access to the Google Analytics 4 Data API. Run custom reports, check realtime active users, analyze top events, view daily user trends, and explore retention cohorts.

Features

• Custom reports with arbitrary metrics, dimensions, and date ranges
• Realtime active users by country and device
• Top events by count over configurable time windows
• Daily users (DAU, sessions, new users) time series
• Retention cohorts by first-session date
• Supports 3 authentication methods (file path, inline JSON, base64)
• Works with Claude Code, Gemini CLI, and any MCP-compatible client

Quick Start

1. Install

npm install @devli13/mcp-ga4

Or clone locally:

git clone https://github.com/devli13/mcp-ga4.git
cd mcp-ga4
npm install

2. Enable the Google Analytics Data API

1. Go to the Google Cloud Console API Library
2. Select your project
3. Click Enable

3. Set up authentication

Create a service account (or reuse an existing Firebase service account) and grant it Viewer access on your GA4 property:

1. Go to Google Analytics Admin > Property Access Management
2. Add the service account email with Viewer role
3. Note your Property ID (9-digit number from Property Settings, not the G-XXXXX measurement ID)

4. Configure

Add to your .mcp.json (Claude Code) or .gemini/settings.json (Gemini CLI):

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["-y", "@devli13/mcp-ga4"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

Authentication Methods

The server checks for credentials in this order:

Method	Environment Variable	Description
File path (recommended)	GOOGLE_APPLICATION_CREDENTIALS	Standard Google SDK auth. Path to a service account JSON file.
Inline JSON	GA4_SERVICE_ACCOUNT_JSON	The full service account JSON as a string. Useful in environments where files aren't practical.
Base64-encoded	GA4_SERVICE_ACCOUNT_B64	Base64-encoded service account JSON. Useful for secret managers that don't support multi-line values.

At least one must be set. The server exits with a clear error message if no credentials are found.

Configuration

Environment Variable	Required	Description
GA4_PROPERTY_ID	Yes*	Default GA4 property ID (9-digit number). Can be overridden per-call via propertyId parameter.
GOOGLE_APPLICATION_CREDENTIALS	One of three	Path to service account JSON file
GA4_SERVICE_ACCOUNT_JSON	One of three	Inline service account JSON string
GA4_SERVICE_ACCOUNT_B64	One of three	Base64-encoded service account JSON

* Required unless you pass propertyId in every tool call.

Tools

Tool	Description	Key Parameters
ga4_run_report	Run an arbitrary GA4 report	metrics, dimensions, dateRanges, orderBy, limit
ga4_realtime	Active users right now by country/device	propertyId
ga4_top_events	Top events by count over last N days	days, limit
ga4_daily_users	DAU / sessions / new users time series	days
ga4_retention	Retention cohorts by first-session date	days, limit
ga4_list_properties	Show the configured default property	--

Example: daily users last 7 days

{
  "name": "ga4_daily_users",
  "arguments": {
    "days": 7
  }
}

Example: custom report with dimensions

{
  "name": "ga4_run_report",
  "arguments": {
    "metrics": ["activeUsers", "sessions", "engagementRate"],
    "dimensions": ["country", "deviceCategory"],
    "dateRanges": [{ "startDate": "7daysAgo", "endDate": "today" }],
    "orderBy": "activeUsers",
    "limit": 20
  }
}

Limitations

• GA4 Data API quotas apply (typically 50,000 requests/day per project). See Google's quota docs.
• Realtime reports are limited to the last 30 minutes of data.
• ga4_list_properties returns only the configured default property. Use the Admin API for a full property listing.
• The service account must have Viewer access granted at the GA4 property level (not just GCP project IAM).

Contributing

Issues and pull requests are welcome! Please open an issue first to discuss significant changes.

License

MIT