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

Status

• Version: 0.2.1 · npm
• Auth: OAuth via Google ADC (GOOGLE_APPLICATION_CREDENTIALS)
• Tools: 34 (accounts, schema, reporting, admin)
• 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

One-click install

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-analytics
npm install
npm 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.

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.

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 (34)

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

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

Notes

• Read-only posture. All tools are read-only except ga_create_report_task and ga_create_audience_export, which materialise server-side snapshots and charge quota (annotated readOnlyHint: false, destructiveHint: true, idempotentHint: false) without modifying property configuration. Hosts can gate the two creation tools behind explicit user approval.
• Alpha endpoints. Audiences, channel groups, BigQuery links, the global site tag, change history (Admin API), and report tasks (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.