Google Analytics 4

@mindstone/mcp-server-google-analytics

[npm version] [License: FSL-1.1-MIT]

Google Analytics 4 MCP server for Model Context Protocol hosts. Discover account/property structure, explore the live schema, run reports (with row-volume safety), create large asynchronous exports, and inspect admin configuration through a standardised MCP interface. With writes explicitly enabled, it can also set up and change property configuration: key events, custom dimensions and metrics, audiences, channel groups, data streams, enhanced measurement, event create and edit rules, calculated metrics, annotations, attribution, Measurement Protocol secrets, product links, and data retention.

Status

• Version: 0.2.1 · npm
• Auth: OAuth via Google ADC (GOOGLE_APPLICATION_CREDENTIALS)
• Tools: 91 (accounts, schema, reporting, admin, admin writes)
• Surface: cloud-api
• Machine-readable: STATUS.json

Requirements

• Node.js 20+
• npm
• Google Application Default Credentials (ADC) with the analytics.readonly scope, or a service account JSON with access to the GA4 property
• For write tools: GA4_ALLOW_WRITES=true, credentials with the analytics.edit scope, and the Editor role on the property

One-click install

[Add to Cursor] [Add to VS Code] [Add to VS Code Insiders]

After clicking the button, your host will prompt you to fill: GOOGLE_APPLICATION_CREDENTIALS.

{  "mcpServers": {    "Google Analytics 4": {      "command": "npx",      "args": [        "-y",        "@mindstone/mcp-server-google-analytics"      ],      "env": {        "GOOGLE_APPLICATION_CREDENTIALS": ""      }    }  }}

Quick Start

Install & build

cd <path-to-repo>/connectors/google-analyticsnpm installnpm run build

npx (once published)

npx -y @mindstone/mcp-server-google-analytics

Local

node dist/index.js

Authentication

This server uses Google Application Default Credentials (ADC). Mint ADC for a user account by installing the Google Cloud CLI and running:

gcloud auth application-default login \  --scopes=https://www.googleapis.com/auth/analytics.readonly \  --client-id-file=/absolute/path/to/oauth-client-secret.json

The --client-id-file is optional but strongly recommended — using your own OAuth client avoids the shared gcloud quota and gives you a stable verification footprint. You'll need a Google Cloud project with the Google Analytics Admin API and Google Analytics Data API enabled.

For service accounts, set GOOGLE_APPLICATION_CREDENTIALS to the absolute path of the service-account JSON. The service account must be granted access to the GA4 property in the GA4 Admin UI.

Enabling writes

Write tools are registered but refuse to run (WRITES_DISABLED) unless GA4_ALLOW_WRITES=true. To use them, mint ADC with the edit scope instead:

gcloud auth application-default login \  --scopes=https://www.googleapis.com/auth/analytics.edit \  --client-id-file=/absolute/path/to/oauth-client-secret.json

The account (or service account) also needs the Editor role on the GA4 property. Service-account credentials request the edit scope automatically when writes are enabled; user ADC keeps whatever scope it was minted with.

Configuration

Environment variables

• GOOGLE_APPLICATION_CREDENTIALS — required. Absolute path to ADC or service-account JSON. Node does not expand ~ or %APPDATA% — provide a fully-resolved path.
• GA4_PROPERTY_ID — optional. Default GA4 property ID (e.g. 123456789). Tools fall back to this when property_id is not passed in the call.
• GA4_ALLOW_WRITES — optional. Set to true (or 1) to allow the write tools to change GA4 configuration. Any other value, or unset, keeps the connector read-only.

Host configuration examples

Claude Desktop / Cursor

{  "mcpServers": {    "GoogleAnalytics": {      "command": "npx",      "args": ["-y", "@mindstone/mcp-server-google-analytics"],      "env": {        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/you/.config/gcloud/application_default_credentials.json",        "GA4_PROPERTY_ID": "123456789"      }    }  }}

Local development (no npm publish needed)

{  "mcpServers": {    "GoogleAnalytics": {      "command": "node",      "args": ["<path-to-repo>/connectors/google-analytics/dist/index.js"],      "env": {        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/credentials.json",        "GA4_PROPERTY_ID": "123456789"      }    }  }}

Tools (91)

Account & property

• ga_list_account_summaries — discover available accounts and properties
• ga_list_properties — flat list of GA4 properties with optional filtering
• ga_get_property_details — currency, time zone, industry category, service level

Schema discovery

• ga_get_metadata — live property schema
• ga_get_property_schema — same data with summary counts
• ga_search_schema — keyword search across dimensions and metrics
• ga_list_dimension_categories, ga_list_metric_categories
• ga_get_dimensions_by_category, ga_get_metrics_by_category
• ga_check_compatibility — verify dimension/metric combinations before reporting

Reporting

• ga_run_report — core report with row-volume safety (estimate, opt-in to large datasets, automatic aggregation suggestions)
• ga_run_pivot_report — cross-tabulated reports
• ga_batch_run_reports — up to 5 reports in one call
• ga_run_realtime_report — last 30 minutes of activity
• ga_get_property_quotas_snapshot — remaining tokens / requests
• ga_run_funnel_report — step-by-step completion and drop-off, with optional breakdown, next action, and trended view (v1alpha)

Large exports

• ga_create_report_task — start an asynchronous report task for large exports (no synchronous timeout, no row-volume gate)
• ga_get_report_task — poll task state until ACTIVE
• ga_query_report_task — page task rows (up to 250,000 per page)
• ga_create_audience_export — snapshot the users in an audience (incl. predictive segments); charges audience-export quota tokens
• ga_get_audience_export — poll export state until ACTIVE
• ga_list_audience_exports — find and reuse existing exports
• ga_query_audience_export — page user-level rows from an ACTIVE export

Admin visibility

• ga_list_audiences — audiences configured on the property, with filter clauses
• ga_list_channel_groups — channel groups and their grouping rules
• ga_get_custom_dimensions_and_metrics
• ga_list_google_ads_links
• ga_list_key_events
• ga_list_data_streams
• ga_get_global_site_tag — gtag.js snippet for the first web stream
• ga_list_bigquery_links
• ga_get_data_retention_settings
• ga_list_firebase_links
• ga_search_change_history_events
• ga_get_enhanced_measurement_settings — automatic events on a web stream
• ga_list_event_create_rules — rules that derive new events on a stream
• ga_list_measurement_protocol_secrets — secret values are returned; treat as sensitive
• ga_list_annotations — chart annotations (v1alpha)
• ga_get_attribution_settings — attribution model and lookback windows (v1alpha)
• ga_list_calculated_metrics — formula metrics (v1alpha)
• ga_list_event_edit_rules — rules that rename or modify events on a stream (v1alpha)
• ga_get_google_signals_settings (v1alpha)
• ga_get_data_sharing_settings — account-level

Admin writes (require GA4_ALLOW_WRITES=true)

Every write is annotated readOnlyHint: false, destructiveHint: true. Archive, delete, acknowledgement, and data-retention tools also require confirm: true. Update tools change only the fields you pass (the update mask is built from them) and fail with NOTHING_TO_UPDATE if you pass none.

• Key events: ga_create_key_event, ga_update_key_event, ga_delete_key_event
• Custom dimensions: ga_create_custom_dimension, ga_update_custom_dimension, ga_archive_custom_dimension
• Custom metrics: ga_create_custom_metric, ga_update_custom_metric, ga_archive_custom_metric
• Audiences (v1alpha): ga_create_audience, ga_update_audience, ga_archive_audience
• Channel groups (v1alpha): ga_create_channel_group, ga_update_channel_group, ga_delete_channel_group
• Event create rules (v1alpha): ga_create_event_create_rule, ga_update_event_create_rule, ga_delete_event_create_rule
• Property: ga_create_property, ga_update_property, ga_delete_property (moves to trash for 35 days), ga_acknowledge_user_data_collection
• Data streams: ga_create_web_data_stream, ga_update_data_stream, ga_delete_data_stream
• Enhanced measurement (v1alpha): ga_update_enhanced_measurement_settings
• Measurement Protocol secrets: ga_create_measurement_protocol_secret, ga_delete_measurement_protocol_secret
• Google Ads links: ga_create_google_ads_link, ga_update_google_ads_link, ga_delete_google_ads_link
• Firebase links: ga_create_firebase_link, ga_delete_firebase_link
• BigQuery links (v1alpha): ga_create_bigquery_link, ga_update_bigquery_link, ga_delete_bigquery_link
• Data retention: ga_update_data_retention_settings
• Annotations (v1alpha): ga_create_annotation, ga_update_annotation, ga_delete_annotation
• Attribution (v1alpha): ga_update_attribution_settings
• Calculated metrics (v1alpha): ga_create_calculated_metric, ga_update_calculated_metric, ga_delete_calculated_metric
• Event edit rules (v1alpha): ga_create_event_edit_rule, ga_update_event_edit_rule, ga_delete_event_edit_rule

Explorations, saved reports, and report layouts have no Google API, so they cannot be created or changed by this connector.

Notes

• Read-only by default. Without GA4_ALLOW_WRITES=true, the only tools that create anything are ga_create_report_task and ga_create_audience_export, which materialise server-side snapshots and charge quota without modifying property configuration. The admin write tools refuse with WRITES_DISABLED before any request is sent. All of these are annotated readOnlyHint: false, destructiveHint: true, so hosts can gate them behind explicit user approval.
• Alpha endpoints. Audiences, channel groups, BigQuery links, enhanced measurement, event create and edit rules, annotations, attribution, calculated metrics, Google Signals, the global site tag, change history (Admin API), and report tasks and funnel reports (Data API) are only exposed on Google's v1alpha surfaces today; the corresponding tools note this in their descriptions.
• Untrusted content. Text authored inside the GA4 property — report dimension values (page titles, campaign names, custom-dimension values), audience/display names, descriptions, definition blobs, data-stream stream-data blobs, the global site tag snippet, custom-metadata expressions, vendor-echoed header/dimension names, and vendor error messages — is returned inside <untrusted-content source="…"> envelopes so hosts treat it as data, not instructions. Metric values and resource identifiers stay raw so agents can compose follow-up calls. Resource IDs passed to tools are constrained to the ID charset before URL interpolation (INVALID_RESOURCE_ID on anything else).
• Response validation. Every Google API response is validated against a Zod schema at the boundary; a shape mismatch fails closed with an INVALID_API_RESPONSE error rather than propagating malformed data. Paginated lists follow nextPageToken in full and fail with PAGINATION_LIMIT_EXCEEDED if the API does not stop paging after a generous safety cap — never a silent truncation.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on the second anniversary of release.