GA4 Server

A Model Context Protocol (MCP) server for Google Analytics 4 (GA4) that provides tools for querying GA4 data through the Admin API and Data API.

Features

• Dual Authentication: Supports both OAuth Playground tokens and Service Account credentials
• 8 GA4 Tools:
  • Account and property management (Admin API)
  • Report execution and realtime data (Data API)
  • GTM → GA4 parameter validation (cross-platform orchestration)
• Compatible with Claude Desktop and other MCP-enabled clients
• GTM Integration: Works with GTM MCP Server for end-to-end event validation

Installation

npm install
npm run build

Quick Start (OAuth Setup)

1. Create OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Analytics Data API and Google Analytics Admin API
4. Go to Credentials → Create Credentials → OAuth client ID
5. Select Desktop app as the application type
6. Download or copy the Client ID and Client Secret

2. Run Setup Script

# Set your OAuth credentials
export GA4_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GA4_CLIENT_SECRET="your-client-secret"

# Run setup to authenticate with Google
npm run setup

This will:

• Open a browser for Google login
• Request read-only access to Google Analytics
• Save tokens to ~/.ga4-mcp/tokens.json

3. Use the Server

Once authenticated, you can use the MCP server with Claude Desktop or other clients.

Authentication

The server supports two authentication methods, checked in this order:

1. OAuth Playground Tokens (Recommended for personal use)

Set these environment variables:

• GA4_ACCESS_TOKEN - OAuth access token
• GA4_REFRESH_TOKEN - OAuth refresh token
• GA4_CLIENT_ID - OAuth client ID
• GA4_CLIENT_SECRET - OAuth client secret

Or create ~/.ga4-mcp/tokens.json:

{
  "access_token": "your-access-token",
  "refresh_token": "your-refresh-token",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

2. Service Account (Recommended for production)

Options (in priority order):

1. Set GA4_SERVICE_ACCOUNT_JSON environment variable with JSON string
2. Set GOOGLE_APPLICATION_CREDENTIALS to the JSON file path
3. Place JSON file at ~/.ga4-mcp/credentials.json
4. Place JSON file in ./Credential/ folder

Usage

Claude Desktop Configuration

Add to your Claude Desktop configuration (~/.config/claude-desktop/config.json):

{
  "mcpServers": {
    "ga4": {
      "command": "node",
      "args": ["/path/to/ga4-mcp-server/dist/index.js"],
      "env": {
        "GA4_ACCESS_TOKEN": "your-access-token",
        "GA4_REFRESH_TOKEN": "your-refresh-token",
        "GA4_CLIENT_ID": "your-client-id",
        "GA4_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Direct Execution

# With OAuth environment variables
GA4_ACCESS_TOKEN="..." GA4_REFRESH_TOKEN="..." GA4_CLIENT_ID="..." GA4_CLIENT_SECRET="..." node dist/index.js

# With Service Account
GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json" node dist/index.js

Available Tools

Admin API Tools

Tool	Description
ga4_account_summaries	List all GA4 accounts and properties the user has access to
ga4_property_details	Get detailed information about a specific property
ga4_google_ads_links	List Google Ads accounts linked to a property
ga4_property_annotations	List annotations for a property (limited support)

Data API Tools

Tool	Description
ga4_run_report	Run a standard GA4 report with dimensions, metrics, and date ranges
ga4_run_realtime_report	Run a realtime report for the last 30 minutes
ga4_custom_dimensions_metrics	Get custom dimensions and metrics defined for a property

GTM Validation Tool

Tool	Description
ga4_validate_gtm_params	Validate GTM event parameters against GA4 custom dimensions and data collection

Example Usage

Get Account Summaries

{
  "tool": "ga4_account_summaries"
}

Run a Report

{
  "tool": "ga4_run_report",
  "arguments": {
    "propertyId": "123456789",
    "dateRanges": [
      {"startDate": "30daysAgo", "endDate": "yesterday"}
    ],
    "dimensions": ["country", "deviceCategory"],
    "metrics": ["activeUsers", "sessions"]
  }
}

Run Realtime Report

{
  "tool": "ga4_run_realtime_report",
  "arguments": {
    "propertyId": "123456789",
    "dimensions": ["country"],
    "metrics": ["activeUsers"]
  }
}

Validate GTM Parameters

{
  "tool": "ga4_validate_gtm_params",
  "arguments": {
    "propertyId": "123456789",
    "gtmEvents": [
      {
        "eventName": "purchase",
        "parameters": ["transaction_id", "value", "currency"]
      }
    ],
    "startDate": "7daysAgo",
    "endDate": "yesterday"
  }
}

Or with GTM Export JSON:

{
  "tool": "ga4_validate_gtm_params",
  "arguments": {
    "propertyId": "123456789",
    "gtmExportJson": { "...GTM container export data..." }
  }
}

GTM Integration (Claude Agent Orchestration)

This server works with the GTM MCP Server to provide end-to-end validation of GTM event parameters in GA4.

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        Claude Agent                                 │
│                    (Orchestrator Role)                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ① GTM MCP Server                  ② GA4 MCP Server                │
│  (gtmAgent/mcp-server)             (ga4-mcp-server)                 │
│                                                                     │
│  gtm_export_full()                 ga4_validate_gtm_params()        │
│  gtm_tag().list()                  ga4_custom_dimensions_metrics()  │
│       │                            ga4_run_report()                 │
│       │                                   ▲                         │
│       └───────────────────────────────────┘                         │
│                Agent relays data                                    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Workflow

1. Extract from GTM: gtm_export_full() → Get GA4 Event tags and parameters
2. Validate in GA4: ga4_validate_gtm_params() → Check registration and collection
3. Get recommendations: Parameters not registered or not collecting data

Claude Desktop Configuration (Both Servers)

{
  "mcpServers": {
    "gtm": {
      "command": "node",
      "args": ["/path/to/gtmAgent/mcp-server/dist/index.js"],
      "env": {}
    },
    "ga4": {
      "command": "node",
      "args": ["/path/to/ga4-mcp-server/dist/index.js"],
      "env": {
        "GA4_ACCESS_TOKEN": "your-access-token",
        "GA4_REFRESH_TOKEN": "your-refresh-token",
        "GA4_CLIENT_ID": "your-client-id",
        "GA4_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

API Call Efficiency

Scenario	Traditional	Optimized	Reduction
5 events × 21 params	105 calls	22 calls	79%
14 events × 32 params	448 calls	33 calls	93%

The validation tool queries metadata once, then makes one API call per unique parameter instead of per event-parameter combination.

API Documentation References

• GA4 Admin API
• GA4 Data API
• Standard Dimensions
• Standard Metrics
• Realtime Dimensions
• Realtime Metrics

Required Google API Scopes

The server uses the following scope:

• https://www.googleapis.com/auth/analytics.readonly

License

MIT