GA4 MCP Server

GA4 MCP 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

Data API Tools

GTM Validation Tool

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"]
      }