Skip to main content
Glama
GA4 MCP Server

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

Related MCP server: MCP Google Analytics Server

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:

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

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

Required Google API Scopes

The server uses the following scope:

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

License

MIT

Available Tools

8 tools
ga4_account_summariesA

Retrieves information about the user's Google Analytics accounts and properties. Returns a list of all GA4 accounts and their associated properties that the authenticated user has access to.

Inputs: no named parameters.

ga4_custom_dimensions_metricsA

Retrieves the custom dimensions and metrics defined for a GA4 property. Use this to discover what custom definitions are available before running reports.

Inputs: propertyId (required).

ga4_property_annotationsB

Returns annotations for a GA4 property. Annotations are notes that mark specific dates or periods, typically used to record events like releases, campaigns, or traffic changes.

Inputs: propertyId (required).

ga4_property_detailsB

Returns details about a specific GA4 property including its name, display name, time zone, currency, industry category, and other settings.

Inputs: propertyId (required).

ga4_run_realtime_reportA

Runs a Google Analytics Data API realtime report. Returns real-time analytics data for the last 30 minutes.

Hints for arguments

Hints for dimensions

Use realtime dimensions from https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#dimensions Or user-scoped custom dimensions (apiName starting with "customUser:")

Hints for metrics

Use realtime metrics from https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#metrics Note: Realtime reports cannot use custom metrics.

Inputs: propertyId (required), dimensions (required), metrics (required), dimensionFilter, +4 more.

ga4_run_reportA

Runs a Google Analytics Data API report. Returns analytics data based on the specified dimensions, metrics, and date ranges.

Hints for arguments

Hints for dimensions

The dimensions list must consist solely of either:

  1. Standard dimensions from https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#dimensions

  2. Custom dimensions for the property. Use ga4_custom_dimensions_metrics to retrieve custom dimensions.

Hints for metrics

The metrics list must consist solely of either:

  1. Standard metrics from https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#metrics

  2. Custom metrics for the property. Use ga4_custom_dimensions_metrics to retrieve custom metrics.

Hints for dateRanges

Examples:

  • Single range: [{"startDate": "2025-01-01", "endDate": "2025-01-31"}]

  • Relative: [{"startDate": "30daysAgo", "endDate": "yesterday"}]

  • Multiple: [{"startDate": "2025-01-01", "endDate": "2025-01-31", "name": "Jan"}, {"startDate": "2025-02-01", "endDate": "2025-02-28", "name": "Feb"}]

Hints for dimensionFilter

Example: {"filter": {"fieldName": "eventName", "stringFilter": {"matchType": "BEGINS_WITH", "value": "page"}}}

Hints for orderBys

Example: [{"dimension": {"dimensionName": "eventName"}, "desc": false}] or [{"metric": {"metricName": "eventCount"}, "desc": true}]

Inputs: propertyId (required), dateRanges (required), dimensions (required), metrics (required), +7 more.

ga4_validate_gtm_paramsA

GTM에서 보내는 이벤트 파라미터가 GA4에 제대로 수집되는지 검증합니다.

사용 방법

방법 1: GTM 이벤트 목록 직접 전달

gtmEvents 배열로 이벤트별 파라미터를 전달합니다.

방법 2: GTM Container Export JSON 전달

GTM에서 컨테이너를 Export한 JSON 파일 내용을 gtmExportJson으로 전달하면 자동으로 파싱합니다.

검증 항목

  1. 파라미터가 GA4 커스텀 디멘션으로 등록되어 있는지

  2. 등록된 파라미터가 실제로 데이터를 수집하고 있는지

  3. 미등록/미수집 파라미터에 대한 권장사항

API 호출 효율성

  • 기존: 이벤트 수 × 파라미터 수 = N×M 호출

  • 최적화: 1(메타데이터) + 고유 파라미터 수 = 1+P 호출

Inputs: propertyId (required), gtmEvents, gtmExportJson, startDate, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting specific GA4 resources or operations. For example, ga4_account_summaries retrieves account-level metadata, ga4_run_report handles standard analytics queries, and ga4_validate_gtm_params focuses on data quality validation. There is no functional overlap between tools, making tool selection straightforward for an agent.

    Naming Consistency5/5

    All tools follow a consistent 'ga4_' prefix with descriptive snake_case naming that clearly indicates their function (e.g., ga4_property_details, ga4_run_realtime_report). The naming pattern is uniform throughout the set, making it predictable and easy to understand.

    Tool Count5/5

    With 8 tools, this server is well-scoped for GA4 operations. It covers essential areas like metadata retrieval (accounts, properties, custom definitions), reporting (standard and realtime), and data validation, without being overwhelming or sparse. Each tool serves a clear, necessary function in the analytics workflow.

    Completeness4/5

    The tool set provides strong coverage for core GA4 operations including metadata access, reporting, and data validation. However, there are minor gaps such as the absence of tools for creating or managing resources (e.g., creating custom dimensions or annotations) or handling administrative tasks like user permissions, which could limit full lifecycle management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers