[Video](https://www.youtube.com/watch?v=PT4wGPxWiRQ) The [Google Analytics Model Context Protocol (MCP)](https://github.com/googleanalytics/google-analytics-mcp) server lets you connect your Google Analytics data to large language models (LLMs) and AI agents, such as Gemini. You can use the MCP server to query reports in natural language, inspect property configurations, and build custom analytics agents. [Set up the MCP server](https://developers.google.com/analytics/devguides/MCP.md.txt#prerequisites) [View on GitHub](https://github.com/googleanalytics/google-analytics-mcp) [Watch the Setup Tutorial](https://youtu.be/nS8HLdwmVlY) > [!NOTE] > **Note:** The MCP server is available for *read* requests only. It can't create, modify, or delete your Google Analytics configuration or settings. ## Prerequisites Before configuring the Google Analytics MCP server, complete the following requirements: 1. **Install Python and a package runner:** - Install [Python 3.10 or higher](https://www.python.org/downloads/). - Install [`pipx`](https://pipx.pypa.io/stable/installation/) or [`uv`](https://docs.astral.sh/uv/getting-started/installation/) (`uvx`) to run the MCP server in an isolated Python environment. 2. **Enable the Google Analytics APIs in :** - Create or select a [project](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - Enable both the [Google Analytics Admin API](https://console.cloud.google.com/apis/library/analyticsadmin.googleapis.com) (`analyticsadmin.googleapis.com`) and the [Google Analytics Data API](https://console.cloud.google.com/apis/library/analyticsdata.googleapis.com) (`analyticsdata.googleapis.com`) in your project: ```bash gcloud services enable analyticsadmin.googleapis.com \ analyticsdata.googleapis.com \ --project=YOUR_PROJECT_ID ``` 3. **Grant Google Analytics property access:** - In the [Google Analytics UI](https://analytics.google.com), grant your user account or service account at least the **Viewer** role (`roles/analytics.viewer`) on the target Google Analytics property. For instructions, see [Manage access and data-restriction management](https://support.google.com/analytics/answer/9305788). ## Set up authentication The Google Analytics MCP server authenticates using [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/provide-credentials-adc) with the read-only Google Analytics OAuth 2.0 scope: https://www.googleapis.com/auth/analytics.readonly You can configure ADC using either your Google user account or a service account. ### Option 1: Authenticate with user credentials 1. [Install and initialize](https://cloud.google.com/sdk/docs/install) the gcloud CLI. 2. Run `gcloud auth application-default login` with the required scopes: ```bash gcloud auth application-default login \ --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" ``` If you use a downloaded OAuth 2.0 desktop or web client configuration file (see [Manage OAuth clients](https://support.google.com/cloud/answer/15549257)), pass `--client-id-file`: ```bash gcloud auth application-default login \ --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" \ --client-id-file=YOUR_CLIENT_JSON_FILE ``` 3. When the command finishes, copy the credentials path printed to the console (`Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]`). You use this path in `GOOGLE_APPLICATION_CREDENTIALS` when configuring your MCP client. ### Option 2: Authenticate with a service account To authenticate with a [service account](https://cloud.google.com/iam/docs/service-accounts-create) that has **Viewer** access to your Google Analytics property: - **Service account JSON key file:** Set `GOOGLE_APPLICATION_CREDENTIALS` in your MCP client configuration to the absolute path of your service account JSON file. - **Service account impersonation:** Generate ADC credentials by impersonating the service account with the gcloud CLI: ```bash gcloud auth application-default login \ --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \ --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" ``` ## Configure your MCP client The server is published on PyPI as [`analytics-mcp`](https://pypi.org/project/analytics-mcp/) and exposes both the `analytics-mcp` and `google-analytics-mcp` console scripts. In the following configurations, replace: - `PATH_TO_CREDENTIALS_JSON` with the absolute path to your ADC or service account JSON file. - `YOUR_PROJECT_ID` with the [project ID](https://support.google.com/googleapi/answer/7014113) where you enabled the Google Analytics APIs. ### Antigravity CLI and Antigravity IDE > [!NOTE] > **Note:** Gemini CLI is deprecated. If you're migrating from Gemini CLI (`~/.gemini/settings.json`), see [Migrating from Gemini CLI](https://antigravity.google/docs/cli/gcli-migration). 1. Install [Antigravity CLI](https://antigravity.google/docs/cli/getting-started/) or [Antigravity IDE](https://antigravity.google/docs/mcp). 2. Add the `analytics-mcp` server to `~/.gemini/config/mcp_config.json` (or `.agents/mcp_config.json` in your workspace): ```json { "mcpServers": { "analytics-mcp": { "command": "pipx", "args": ["run", "analytics-mcp"], "env": { "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON", "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID" } } } } ``` 3. Verify that `analytics-mcp` is connected: - **Antigravity CLI:** Run `agy`, then enter `/mcp` to view your configured MCP servers. - **Antigravity IDE:** Open **Settings** \> **Customizations** \> **Installed MCP Servers** and click **Refresh**. ### Claude Desktop and Claude Code For **Claude Desktop** , add the server to your `claude_desktop_config.json` file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows): ```json { "mcpServers": { "analytics-mcp": { "command": "pipx", "args": ["run", "analytics-mcp"], "env": { "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON", "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID" } } } } ``` For **Claude Code**, register the server using the command-line tool: ```bash claude mcp add analytics-mcp \ --scope user \ -e GOOGLE_APPLICATION_CREDENTIALS="PATH_TO_CREDENTIALS_JSON" \ -e GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" \ -- pipx run analytics-mcp ``` ### Cursor Add the server to `.cursor/mcp.json` in your project directory (or `~/.cursor/mcp.json` for global configuration). You can invoke `google-analytics-mcp` using either `uvx` or `pipx`: ```json { "mcpServers": { "google-analytics-mcp": { "command": "uvx", "args": ["--from", "analytics-mcp", "google-analytics-mcp"], "env": { "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON", "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID" } } } } ``` To run the latest development version directly from GitHub using `uvx`, update `"args"`: ```json "args": [ "--from", "git+https://github.com/googleanalytics/google-analytics-mcp.git", "google-analytics-mcp" ] ``` Alternatively, to use `pipx`, change `"command"` to `"pipx"` and set `"args"` to: ```json "command": "pipx", "args": [ "run", "--spec", "git+https://github.com/googleanalytics/google-analytics-mcp.git", "google-analytics-mcp" ] ``` ### Optional: Equip your AI coding agent with skills To help your AI coding agent configure APIs, check dimension and metric compatibility, and generate client library code, pair the MCP server with [Google Analytics AI agent skills](https://developers.google.com/analytics/devguides/agent-skills.md.txt). The skill suite includes the `google-analytics-data-api-basics` and `google-analytics-admin-api-basics` skills for the Google Analytics Data API and Google Analytics Admin API. Install the skills in your project directory by using the `npx` command (requires [Node.js](https://nodejs.org/)), or see [Google Analytics AI agent skills](https://developers.google.com/analytics/devguides/agent-skills.md.txt) for Google Antigravity, Claude Code, Codex, and Cursor options: ```bash npx skills add google/skills/skills/analytics ``` ## Available MCP tools The Google Analytics MCP server uses the [Admin API](https://developers.google.com/analytics/devguides/config/admin/v1.md.txt) and [Data API v1](https://developers.google.com/analytics/devguides/reporting/data/v1.md.txt) to expose read-only tools to your MCP client: - **Account and property discovery (Admin API):** - `get_account_summaries`: Lists the Google Analytics accounts and properties accessible to the authenticated user ([`accountSummaries.list`](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1beta/accountSummaries/list.md.txt)). - `get_property_details`: Returns configuration details for a specific Google Analytics property ([`properties.get`](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1beta/properties/get.md.txt)). - `list_google_ads_links`: Lists links to Google Ads accounts for a property ([`properties.googleAdsLinks.list`](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1beta/properties.googleAdsLinks/list.md.txt)). - `list_property_annotations`: Lists annotations configured for a property ([`properties.reportingDataAnnotations.list`](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.reportingDataAnnotations/list.md.txt)). - **Reporting and schema inspection (Data API v1):** - `get_custom_dimensions_and_metrics`: Retrieves custom dimensions and custom metrics defined for a property ([`getMetadata`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/getMetadata.md.txt)). - `run_report`: Runs a standard Google Analytics report ([`runReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport.md.txt)). - `run_realtime_report`: Runs a Google Analytics realtime report ([`runRealtimeReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport.md.txt)). - `run_funnel_report`: Runs a Google Analytics funnel exploration report ([`runFunnelReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/runFunnelReport.md.txt)). - `run_conversions_report`: Runs a [conversions performance report](https://developers.google.com/analytics/devguides/reporting/data/v1/conversions-api-basics) (`runConversionsReport`). ## Sample prompts Once connected, try asking your AI assistant questions such as: - How many users did I have yesterday? - What were my top selling products yesterday? - I have a marketing budget of $5,000/month and need to generate more revenue. Help me create a data-driven marketing plan. - What custom dimensions and custom metrics are configured in my property? - What are the most popular events in my Google Analytics property over the last 90 days? ## Troubleshooting Use the following checklist to resolve common setup and runtime errors: - **`403 PERMISSION_DENIED` (API not enabled or insufficient property permissions):** - Confirm that both the [Google Analytics Admin API](https://console.cloud.google.com/apis/library/analyticsadmin.googleapis.com) (`analyticsadmin.googleapis.com`) and the [Google Analytics Data API](https://console.cloud.google.com/apis/library/analyticsdata.googleapis.com) (`analyticsdata.googleapis.com`) are enabled in the project specified by `GOOGLE_CLOUD_PROJECT`. - Verify that the authenticating user or service account has at least the **Viewer** role (`roles/analytics.viewer`) on the target Google Analytics property in the [Google Analytics UI](https://analytics.google.com). - If the error states `Request had insufficient authentication scopes`, re-run `gcloud auth application-default login` with the `https://www.googleapis.com/auth/analytics.readonly` and `https://www.googleapis.com/auth/cloud-platform` scopes. - **Missing quota project (`GOOGLE_CLOUD_PROJECT`) or `403 ACCESS_NOT_CONFIGURED`:** - Requests authenticated with user ADC credentials require a quota project with the Google Analytics APIs enabled. Set `"GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"` in your MCP server's `env` configuration, or set the quota project on your ADC file: ```bash gcloud auth application-default set-quota-project YOUR_PROJECT_ID ``` - **`401 UNAUTHENTICATED` or credentials file not found:** - Use an absolute path for `GOOGLE_APPLICATION_CREDENTIALS` (for example, `/Users/username/.config/gcloud/application_default_credentials.json`). Avoid `~` or `$HOME` variables, as many MCP hosts don't expand shell variables inside JSON configuration files. - Re-run `gcloud auth application-default login` if your user credentials have expired. - **Server fails to launch (`spawn pipx ENOENT`, `uvx: command not found`, or Python version errors):** - Confirm that Python 3.10 or higher is installed (`python3 --version`). - Desktop GUI applications (such as Claude Desktop and Cursor) often don't inherit your interactive shell `PATH`. Replace `"pipx"` or `"uvx"` in `"command"` with the absolute binary path returned by `which pipx` or `which uvx` (for example, `/opt/homebrew/bin/pipx` or `/Users/username/.local/bin/pipx`). ## Next steps - [Use Google Analytics AI agent skills](https://developers.google.com/analytics/devguides/agent-skills.md.txt) to guide your AI coding agent when enabling APIs, checking field compatibility, and writing client library code. - Complete the [Google Analytics Data API quickstart](https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart.md.txt) or the [Google Analytics Admin API quickstart](https://developers.google.com/analytics/devguides/config/admin/v1/quickstart.md.txt).