GA4 MCP Server
Allows for the retrieval and listing of Google Ads accounts linked to specific Google Analytics 4 properties.
Provides comprehensive tools for querying Google Analytics 4 (GA4) data, including property management, report execution via the Data API, and realtime data monitoring.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GA4 MCP Server show me a report of active users by country for the last 30 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 buildQuick Start (OAuth Setup)
1. Create OAuth Credentials
Go to Google Cloud Console
Create a new project or select an existing one
Enable the Google Analytics Data API and Google Analytics Admin API
Go to Credentials → Create Credentials → OAuth client ID
Select Desktop app as the application type
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 setupThis 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 tokenGA4_REFRESH_TOKEN- OAuth refresh tokenGA4_CLIENT_ID- OAuth client IDGA4_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):
Set
GA4_SERVICE_ACCOUNT_JSONenvironment variable with JSON stringSet
GOOGLE_APPLICATION_CREDENTIALSto the JSON file pathPlace JSON file at
~/.ga4-mcp/credentials.jsonPlace 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.jsAvailable Tools
Admin API Tools
Tool | Description |
| List all GA4 accounts and properties the user has access to |
| Get detailed information about a specific property |
| List Google Ads accounts linked to a property |
| List annotations for a property (limited support) |
Data API Tools
Tool | Description |
| Run a standard GA4 report with dimensions, metrics, and date ranges |
| Run a realtime report for the last 30 minutes |
| Get custom dimensions and metrics defined for a property |
GTM Validation Tool
Tool | Description |
| 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
Extract from GTM:
gtm_export_full()→ Get GA4 Event tags and parametersValidate in GA4:
ga4_validate_gtm_params()→ Check registration and collectionGet 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 toolsga4_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_google_ads_linksA
Returns a list of links to Google Ads accounts for a GA4 property. Shows which Google Ads accounts are connected to the property for data sharing.
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:
Standard dimensions from https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#dimensions
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:
Standard metrics from https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#metrics
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으로 전달하면 자동으로 파싱합니다.
검증 항목
파라미터가 GA4 커스텀 디멘션으로 등록되어 있는지
등록된 파라미터가 실제로 데이터를 수집하고 있는지
미등록/미수집 파라미터에 대한 권장사항
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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
Connect Google Analytics to ChatGPT. Query GA4 data in plain English and get instant insights.
Hosted Google Analytics 4 MCP server, with each action switched on or off per account.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Google Analytics APIs to fetch reports, manage properties, data streams, conversion events, and custom dimensions/metrics through OAuth2 authentication.64 npm6MIT
- AlicenseAqualityCmaintenanceEnables comprehensive integration with Google Analytics 4, allowing users to read analytics reports and send custom events through both the Data API and Measurement Protocol v2.26625 npm3MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to query Google Analytics 4 data, including listing accounts and properties, running historical and real-time reports with customizable metrics and dimensions.MIT
- AlicenseNot gradedqualityCmaintenanceEnables natural-language access to Google Analytics 4 properties and reports, including page views, users, events, traffic sources, device metrics, and custom reports, with automatic OAuth 2.0 authentication and token management.MIT