# mcp-google-analytics [Health: Active]

**Category:** 🎯 Marketing  
**Repository:** https://github.com/leonardosepulvedat/mcp-google-analytics  
**GitHub Stars:** 2  
**npm Downloads (last month):** 6885  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-google-analytics

## Description
GA4 MCP that reads AND writes: reports, funnels, audits, and server-side events. 26 tools.

## Tools
Capabilities this server exposes over MCP:

- **ga_run_report** — Run a custom Google Analytics report with dimensions and metrics.

⚠️ TOKEN OPTIMIZATION: Use 'limit' to control result size (default: 10).
This tool can consume significant tokens with large datasets.

Common dimensions: date, city, country, deviceCategory, browser, pagePath, eventName
Common metrics: activeUsers, sessions, screenPageViews, conversions, totalRevenue
- **ga_run_realtime_report** — Get real-time Google Analytics data (last 30 minutes).

⚠️ TOKEN OPTIMIZATION: Use 'limit' to control result size (default: 10).

Common dimensions: city, country, deviceCategory, unifiedScreenName
Common metrics: activeUsers, screenPageViews, conversions
- **ga_get_metadata** — Get available dimensions and metrics metadata for your GA4 property.

⚠️ TOKEN OPTIMIZATION: This returns ALL available dimensions and metrics.
Response can be large (~500+ items). Use sparingly and cache results when possible.
- **ga_list_accounts** — List all Google Analytics accounts accessible to the service account.

Use this to find account IDs for listing properties.
- **ga_list_properties** — List Google Analytics properties.

Optionally filter by account ID. Without an account ID, properties from all
accessible accounts are aggregated.
- **ga_get_property** — Get details about a GA4 property (the configured one, or any accessible property via propertyId).
- **ga_list_data_streams** — List data streams for the configured GA4 property.

Use this to find measurement IDs for Measurement Protocol.
- **ga_run_pivot_report** — Run a pivot table report with row and column dimensions.

⚠️ TOKEN OPTIMIZATION: Pivot reports can be VERY large.
Limit dimensions and use small date ranges. Recommended for analysis, not raw data extraction.
- **ga_run_funnel_report** — Run a funnel analysis report to track user progression through steps (Data API v1alpha).

Each step matches an event: set 'eventName' per step (defaults to the step name).
For advanced matching, pass a full 'filterExpression' instead.
- **ga_batch_run_reports** — Run multiple reports in a single request.

⚠️ TOKEN OPTIMIZATION: Can return LARGE amounts of data.
Limit to 2-5 reports per batch. Each report should have small limits.
- **ga_get_account_summaries** — Get a compact overview of all accessible GA accounts and their properties in a single call.

The fastest way to discover account IDs, property IDs, and property names.
- **ga_list_custom_dimensions** — List all custom dimensions defined for the configured GA4 property.

Use this to discover custom dimension API names (e.g., "customEvent:plan_type") for reports.
- **ga_list_custom_metrics** — List all custom metrics defined for the configured GA4 property.

Use this to discover custom metric API names for reports.
- **ga_list_key_events** — List the key events (conversions) configured for the GA4 property.

Useful to know which event names count as conversions before building reports or sending events.
- **ga_list_google_ads_links** — List Google Ads accounts linked to a GA4 property.
- **ga_check_compatibility** — Check whether a combination of dimensions and metrics is valid for this property BEFORE running a report.

Avoids wasted report requests and token-heavy error loops. Also lists which other fields remain compatible with the given combination.
- **ga_send_event** — Send a custom event to Google Analytics via Measurement Protocol.

Use this for tracking custom user actions, conversions, or any GA4 event.
Events are processed asynchronously and appear in reports within minutes.

Common events: click, form_submit, video_play, file_download, custom_conversion
- **ga_validate_event** — Validate an event before sending it to Google Analytics.

Uses GA4's debug endpoint to check for errors without recording the event.
Returns validation messages and errors if any.
- **ga_send_pageview** — Send a page view event to Google Analytics.

Standard event for tracking page/screen views. Automatically uses 'page_view' event name.
- **ga_send_purchase** — Send an ecommerce purchase event to Google Analytics.

Standard event for tracking completed purchases with transaction details and items.
- **ga_send_login** — Send a login event to Google Analytics.

Standard event for tracking user logins with authentication method.
- **ga_send_signup** — Send a sign-up event to Google Analytics.

Standard event for tracking new user registrations.
- **ga_send_add_to_cart** — Send an add to cart event to Google Analytics.

Ecommerce event for tracking when items are added to shopping cart.
- **ga_send_begin_checkout** — Send a begin checkout event to Google Analytics.

Ecommerce event for tracking when users start the checkout process.
- **ga_send_view_item** — Send a view item event to Google Analytics.

Ecommerce event for tracking product/item detail views. Completes the standard
funnel: view_item → add_to_cart → begin_checkout → purchase.
- **ga_send_refund** — Send a refund event to Google Analytics.

Ecommerce event for full or partial refunds. Omit 'items' for a full refund;
include them (with quantities) for a partial refund. Use the same transaction_id
as the original purchase.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-google-analytics": {
    "command": "npx",
    "args": ["-y","mcp-google-analytics"],
    "env": {
      "GA_SERVICE_ACCOUNT_JSON": "",
      "GA_PROPERTY_ID": "",
      "GA_MEASUREMENT_ID": "",
      "GA_API_SECRET": ""
    }
  }
}
```

**Requires environment variables:** `GA_SERVICE_ACCOUNT_JSON`, `GA_PROPERTY_ID`, `GA_MEASUREMENT_ID`, `GA_API_SECRET` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What mcp-google-analytics does

The mcp-google-analytics MCP server gives an AI agent access to Google Analytics 4 data and selected administration details. Its read operations use the Google Analytics Data API, while event submission uses Measurement Protocol v2. This supports workflows that combine analysis, configuration checks, event delivery, and verification.

The server includes 26 tools covering custom reports, realtime reports, funnels, pivot reports, account and property discovery, data streams, metadata, custom dimensions, custom metrics, key events, linked Google Ads accounts, and compatibility checks. It can also send custom events, page or screen views, and purchases, or validate an event without recording it.

## How it works

The server runs as an npm package through `npx` or as a globally installed command. An MCP-compatible client starts the process and supplies credentials through environment variables. Read tools query the configured GA4 property, and each read tool defaults to 10 results to limit response size. Callers can increase the `limit` value and narrow reports with specific dimensions, metrics, and date ranges.

A read tool can receive a `propertyId` argument to override the default property. This makes it possible to query several properties that the service account can access without changing the client configuration. IDs may be provided as numbers or in the `properties/123456789` form. Event submission remains associated with the configured Measurement ID and API secret for its data stream.

## Setup and configuration

Install with `npm install -g mcp-google-analytics`, or run it without a global install using `npx mcp-google-analytics`. Configure `GA_SERVICE_ACCOUNT_JSON` with either a path to a downloaded service-account key or the JSON content itself. Set `GA_PROPERTY_ID` to the numeric GA4 property ID for the default read target.

Before querying data, enable the Google Analytics Data API in Google Cloud and grant the service account Viewer access to the GA4 property. For the mcp-google-analytics MCP server to send events, also set `GA_MEASUREMENT_ID` to the relevant web or app data-stream Measurement ID and `GA_API_SECRET` to a Measurement Protocol API secret.

Claude Desktop and Cursor configurations use the MCP `command` and `args` fields with `npx -y mcp-google-analytics`. Restart the client after changing its configuration. Agencies can omit the default property ID when using per-request `propertyId` values, provided the service account has access to the target properties.

## Tools and capabilities

Read-oriented tools include:

- `ga_run_report` for configurable dimensions and metrics
- `ga_run_realtime_report` for the previous 30 minutes
- `ga_run_funnel_report` and `ga_run_pivot_report` for specialized analyses
- `ga_batch_run_reports` for multiple reports in one request
- `ga_get_metadata` for available dimensions and metrics
- Account, property, data-stream, custom-dimension, custom-metric, key-event, and Google Ads link discovery
- `ga_check_compatibility` for validating dimension and metric combinations

Event tools include `ga_send_event`, `ga_validate_event`, `ga_send_pageview`, and `ga_send_purchase`. The validation tool checks an event through the debug endpoint without recording it. Realtime reporting can then help verify recorded events.

## Limitations and notes

The service account must have access to every property it queries. Sending events is optional and depends on both Measurement Protocol credentials; it is tied to one configured data stream rather than the per-property read override. Metadata and pivot responses can be large, so they should be used selectively. Reports may also consume substantial context if broad date ranges, many dimensions, or high result limits are requested. The mcp-google-analytics MCP server is distributed under the MIT license.

_Full upstream README: https://allmcps.com/mcp/mcp-google-analytics/readme_