Content
# Google Analytics 4 (GA4) MCP Setup Guide
This repository provides a step-by-step setup guide and configuration templates to connect **Google Analytics 4 (GA4)** to your AI-first developer tools and CLI assistants (such as **Claude Code**, **AGI (`agy` cli)**, **Cursor**, **Windsurf**, and **Codex**) using the Model Context Protocol (MCP).
By leveraging `uvx` (via the PyPI package `google-analytics-mcp`), you can run the GA4 MCP server securely in stdio mode without needing to manually install Python dependencies in your workspace.
---
## Prerequisites & Installation
### 1. Google Cloud Platform (GCP) Setup
1. Go to the **[Google Cloud Console](https://console.cloud.google.com/)**.
2. Select or create a project.
3. Enable the following two APIs:
* **[Google Analytics Admin API](https://console.developers.google.com/apis/api/analyticsadmin.googleapis.com/overview)** (Used for retrieving list of available Properties)
* **[Google Analytics Data API](https://console.developers.google.com/apis/api/analyticsdata.googleapis.com/overview)** (Used for querying metrics and traffic reports)
4. Go to **APIs & Services > Credentials** and click **Create Credentials > Service Account**.
5. Give your service account a name (e.g., `ga4-mcp`), click **Create and Continue**, and then click **Done** (no GCP IAM roles are required).
6. Click on your newly created Service Account email in the list, go to the **Keys** tab, click **Add Key > Create New Key**, select **JSON**, and click **Create**. Save the downloaded `.json` key file to a safe location on your computer.
### 2. Google Analytics 4 (GA4) Access Management
1. Copy the email address of the Service Account you just created (e.g., `ga4-mcp@your-project-id.iam.gserviceaccount.com`).
2. Log in to your **[Google Analytics](https://analytics.google.com/)** account.
3. Go to **Admin (管理) > Account Access Management (账号访问权限管理)** (or **Property Access Management** if you only want to grant access to a single property).
4. Click the **+** button in the upper right, add the Service Account Email, and assign it the **Viewer (查看者)** role.
---
## Finding Your GA4 Property ID
If you don't know your GA4 Property ID, you can list all properties accessible by your Service Account key using the following one-liner in your terminal (requires `uv`):
```bash
uv run --with google-analytics-admin python -c "
import os
from google.analytics.admin_v1alpha import AnalyticsAdminServiceClient
os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = '/path/to/your/google-credentials.json'
client = AnalyticsAdminServiceClient()
for summary in client.list_account_summaries():
print(f'Account: {summary.display_name}')
for prop in summary.property_summaries:
print(f' Property: {prop.display_name}, ID: {prop.property.split(\"/\")[-1]}')
"
```
Save the numeric ID of the property you wish to query (e.g. `123456789`).
---
## Configuring Your AI Clients
Copy the absolute path to your downloaded Service Account JSON key, and find your GA4 Property ID. Then, update your respective client configuration:
### 1. AGI / agy CLI (Gemini Coder)
Add the configuration to your project's `.mcp.json` or your global `mcp.json` settings:
```json
{
"mcpServers": {
"google-analytics": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"google-analytics-mcp",
"ga4-mcp-server"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/google-credentials.json",
"GA4_PROPERTY_ID": "YOUR_GA4_PROPERTY_ID"
}
}
}
}
```
### 2. Claude Code
Claude Code reads project-level configuration or global desktop settings. Add this snippet to your `claude_desktop_config.json` (located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"google-analytics": {
"command": "uvx",
"args": [
"--from",
"google-analytics-mcp",
"ga4-mcp-server"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/google-credentials.json",
"GA4_PROPERTY_ID": "YOUR_GA4_PROPERTY_ID"
}
}
}
}
```
### 3. Cursor
1. Go to **Settings > Cursor Settings > Features > MCP**.
2. Click **+ Add New MCP Server**.
3. Fill out the fields:
* **Name**: `google-analytics`
* **Type**: `stdio`
* **Command**: `uvx --from google-analytics-mcp ga4-mcp-server`
4. Add the environment variables:
* Key: `GOOGLE_APPLICATION_CREDENTIALS` | Value: `/path/to/your/google-credentials.json`
* Key: `GA4_PROPERTY_ID` | Value: `YOUR_GA4_PROPERTY_ID`
5. Click **Save**.
### 4. Windsurf
Add the following to your global configuration file (`~/.codeium/config.json`):
```json
{
"mcp": {
"servers": {
"google-analytics": {
"command": "uvx",
"args": [
"--from",
"google-analytics-mcp",
"ga4-mcp-server"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/google-credentials.json",
"GA4_PROPERTY_ID": "YOUR_GA4_PROPERTY_ID"
}
}
}
}
}
```
---
## How to Query GA4
Once configured and the client has been restarted, the AI assistant will automatically recognize the tools. You can query GA4 using plain natural language:
* *"What was the total user traffic on my website yesterday?"*
* *"Show me the distribution of traffic channels for the past 7 days."*
* *"Is there any realtime active traffic right now?"*
The AI will translate your prompt into structured GA4 queries using the exposed API tools (like `run_report`, `run_realtime_report`) and present the aggregated metrics.
