@mindstone/mcp-server-google-analytics

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
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

After clicking the button, your host will prompt you to fill: GOOGLE_APPLICATION_CREDENTIALS.
Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (Google Analytics 4)
{
"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-analytics
npm install
npm run build
npx (once published)
npx -y @mindstone/mcp-server-google-analytics
Local
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"
}
}
}
}
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.