Summary
The Google Analytics MCP server connects Google Analytics 4 data to AI agents and workflows, providing analysis-ready access to website traffic, user behavior, and performance metrics through tools like live schema discovery, server-side aggregation, and safe defaults that minimize data processing overhead. It enables agents to query GA4 properties directly via the Google Analytics Data API using a service account, reducing the need for manual data wrangling and making analytics insights accessible across Claude, ChatGPT, Cursor, and other MCP-compatible platforms. The server solves the problem of agents spending excessive time preparing raw analytics data for analysis by pre-aggregating results server-side and estimating large datasets to prevent workflow disruptions.
Give your AI agent a complete email layer—sending, inbound inboxes, and sandbox testing.
Get 4K emails/month free →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Capacitor makes coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Tools
Public tool metadata for what this MCP can expose to an agent.
25 tools
GOOGLE_ANALYTICS_BATCH_RUN_REPORTSTool to return multiple analytics data reports in a batch. Use when you need to fetch multiple reports for one GA4 property in a single request.2 params
Tool to return multiple analytics data reports in a batch. Use when you need to fetch multiple reports for one GA4 property in a single request.
Parameters* required
propertystringRequired. The property resource name. Format: properties/{property_id}
requestsarrayRequired. Up to 5 individual RunReportRequest objects.
GOOGLE_ANALYTICS_CHECK_COMPATIBILITYTool to list dimensions and metrics compatible with a GA4 report request. Use when you need to validate compatibility of chosen dimensions or metrics before running a report.6 params
Tool to list dimensions and metrics compatible with a GA4 report request. Use when you need to validate compatibility of chosen dimensions or metrics before running a report.
Parameters* required
metricsarrayOptional. List of metrics to check compatibility for.
propertystringRequired. GA4 property resource name. Format: properties/{property_id}.
dimensionsarrayOptional. List of dimensions to check compatibility for.
metricFilterobjectOptional. A FilterExpression for metrics; must follow GA4 FilterExpression JSON schema.
dimensionFilterobjectOptional. A FilterExpression for dimensions; must follow GA4 FilterExpression JSON schema.
compatibilityFilterstringCompatibility status for dimensions or metrics.one of
COMPATIBILITY_UNSPECIFIED · COMPATIBLE · INCOMPATIBLEGOOGLE_ANALYTICS_CREATE_AUDIENCE_EXPORTTool to create an audience export. Use after configuring the audience and dimensions to produce a long-running Operation.3 params
Tool to create an audience export. Use after configuring the audience and dimensions to produce a long-running Operation.
Parameters* required
parentstringParent resource name. Format: properties/{property_id}.
audiencestringAudience resource name to export. Format: properties/{property_id}/audiences/{audience_id}.
dimensionsarrayList of dimensions to include in the export.
GOOGLE_ANALYTICS_CREATE_AUDIENCE_LISTTool to create an audience list. Use when you need to define and asynchronously populate a new AudienceList resource under a GA4 property.4 params
Tool to create an audience list. Use when you need to define and asynchronously populate a new AudienceList resource under a GA4 property.
Parameters* required
parentstringParent property resource name. Format: properties/{property_id}.
audiencestringAudience resource name. Format: properties/{property_id}/audiences/{audience_id}.
dimensionsarrayList of dimensions to include in the audience list output.
webhookNotificationobjectConfiguration for receiving webhook notifications about operation status.
GOOGLE_ANALYTICS_CREATE_EXPANDED_DATA_SETTool to create an expanded data set for a property. Use when you need to combine specific dimensions and metrics into a custom dataset after property creation.2 params
Tool to create an expanded data set for a property. Use when you need to combine specific dimensions and metrics into a custom dataset after property creation.
Parameters* required
parentstringParent property resource name. Format: properties/{propertyId}
expandedDataSetobjectDefinition of the ExpandedDataSet to create.
GOOGLE_ANALYTICS_CREATE_ROLLUP_PROPERTYTool to create a GA4 Roll-up Property and optionally initial source links.4 params
Tool to create a GA4 Roll-up Property and optionally initial source links.
Parameters* required
accountstringRequired. Parent account resource. Format: accounts/{account_id}
timeZonestringRequired. IANA time zone for the roll-up property.
displayNamestringRequired. Display name for the roll-up property.
sourcePropertiesarrayOptional. List of source property resource names to link. Format: properties/{property_id}.
GOOGLE_ANALYTICS_GET_ACCOUNTTool to retrieve a single Account by its resource name. Use when you need detailed account info after confirming the account resource name (e.g., accounts/100).1 params
Tool to retrieve a single Account by its resource name. Use when you need detailed account info after confirming the account resource name (e.g., accounts/100).
Parameters* required
namestringRequired. The resource name of the Account to retrieve. Format: accounts/{account_id}, e.g., 'accounts/100'.
GOOGLE_ANALYTICS_GET_AUDIENCE_EXPORTTool to get configuration metadata for an Audience Export. Use after creating an Audience Export to retrieve its status and details.1 params
Tool to get configuration metadata for an Audience Export. Use after creating an Audience Export to retrieve its status and details.
Parameters* required
namestringRequired. The resource name of the Audience Export to retrieve. Format: properties/{property}/audienceExports/{audienceExport}.
GOOGLE_ANALYTICS_GET_AUDIENCE_LISTTool to get configuration metadata about a specific audience list. Use after confirming the audience list resource name.1 params
Tool to get configuration metadata about a specific audience list. Use after confirming the audience list resource name.
Parameters* required
namestringRequired. The resource name of the Audience List to retrieve. Format: properties/{property}/audienceLists/{audienceList}.
GOOGLE_ANALYTICS_GET_KEY_EVENTTool to retrieve a Key Event. Use after confirming the key event resource name.1 params
Tool to retrieve a Key Event. Use after confirming the key event resource name.
Parameters* required
namestringRequired. Resource name of the Key Event to retrieve. Format: properties/{property}/keyEvents/{keyEvent}.
GOOGLE_ANALYTICS_GET_METADATATool to get metadata for dimensions, metrics, and comparisons for a GA4 property. Use when you need to discover available fields before building a report.1 params
Tool to get metadata for dimensions, metrics, and comparisons for a GA4 property. Use when you need to discover available fields before building a report.
Parameters* required
namestringResource name of the metadata to retrieve. Format: properties/{property_id}/metadata. Use property_id=0 to return only universal (non-custom) metadata.
GOOGLE_ANALYTICS_GET_PROPERTY_QUOTAS_SNAPSHOTTool to retrieve all property quotas organized by category for a given property. Use when you need to check current quota usage for a GA4 property.1 params
Tool to retrieve all property quotas organized by category for a given property. Use when you need to check current quota usage for a GA4 property.
Parameters* required
propertystringRequired. The property resource. Format: properties/{property_id}.
GOOGLE_ANALYTICS_LIST_ACCOUNTSTool to list all Accounts accessible by the caller. Use when you need to enumerate all Google Analytics accounts your credentials can access.3 params
Tool to list all Accounts accessible by the caller. Use when you need to enumerate all Google Analytics accounts your credentials can access.
Parameters* required
pageSizeintegerOptional. Maximum number of accounts to return. Must be ≥1.
pageTokenstringOptional. Token for retrieving the next page of results.
showDeletedbooleanOptional. Whether to include soft-deleted (trashed) Accounts.
GOOGLE_ANALYTICS_LIST_AUDIENCE_EXPORTSTool to list all audience exports for a GA4 property. Use when you need to fetch its export history after initiating exports.3 params
Tool to list all audience exports for a GA4 property. Use when you need to fetch its export history after initiating exports.
Parameters* required
parentstringRequired. Resource name of the parent property. Format: properties/{property_id}
pageSizeintegerOptional. Maximum number of results to return. Defaults to 200; larger values are coerced to 1000.
pageTokenstringOptional. Token for retrieving the next page of results; other parameters must match original call when paginating.
GOOGLE_ANALYTICS_LIST_AUDIENCE_LISTSTool to list all audience lists for a GA4 property. Use when you need to retrieve a property's configured audience lists after confirming the property ID.3 params
Tool to list all audience lists for a GA4 property. Use when you need to retrieve a property's configured audience lists after confirming the property ID.
Parameters* required
parentstringRequired. Resource name of the parent property. Format: properties/{property_id}
pageSizeintegerOptional. Maximum number of audience lists to return. Defaults to 200; maximum is 1000.
pageTokenstringOptional. Token for retrieving the next page of results.
GOOGLE_ANALYTICS_LIST_AUDIENCESTool to list all audiences on a property. Use when you need to fetch all audiences for a GA4 property after confirming its existence.3 params
Tool to list all audiences on a property. Use when you need to fetch all audiences for a GA4 property after confirming its existence.
Parameters* required
parentstringRequired. Property ID or full resource name. Accepts: '123456789' or 'properties/123456789'
pageSizeintegerOptional. Maximum number of Audiences to return.
pageTokenstringOptional. Token for retrieving the next page of results.
GOOGLE_ANALYTICS_LIST_KEY_EVENTSTool to list Key Events. Use when you need to retrieve all key event definitions for a given property.3 params
Tool to list Key Events. Use when you need to retrieve all key event definitions for a given property.
Parameters* required
parentstringRequired. Resource name of the parent property. Format: properties/{property_id}.
pageSizeintegerOptional. Maximum number of results to return. Must be between 1 and 200.
pageTokenstringOptional. Token for retrieving the next page of results.
GOOGLE_ANALYTICS_LIST_PROPERTIESTool to list GA4 properties under a specific account. Use after obtaining an account ID; supports pagination and including soft-deleted properties.4 params
Tool to list GA4 properties under a specific account. Use after obtaining an account ID; supports pagination and including soft-deleted properties.
Parameters* required
accountstringRequired. The account resource name. Format: accounts/{account_id}
pageSizeintegerOptional. Maximum number of properties to return; must be between 1 and 200.
pageTokenstringOptional. Token returned from a previous call to retrieve the next page of results.
showDeletedbooleanOptional. Whether to include soft-deleted (trashed) properties.
GOOGLE_ANALYTICS_LIST_REPORTING_DATA_ANNOTATIONSTool to list all Reporting Data Annotations on a property. Use when you need to retrieve or inspect annotations for a GA4 property.4 params
Tool to list all Reporting Data Annotations on a property. Use when you need to retrieve or inspect annotations for a GA4 property.
Parameters* required
filterstringRestricts which annotations are listed. Supported fields: name, title, description, annotationDate, annotationDateRange, color; operations: =, !=, <, >, <=, >=, :, =~, !~, NOT, AND, OR; helper functions: annotation_duration(), is_annotation_in_range(startDate,endDate).
parentstringResource name of the property. Format: properties/{property_id}.
pageSizeintegerOptional. Maximum number of annotations to return. Defaults to 50, max 200.
pageTokenstringOptional. Token for retrieving the next page of results.
GOOGLE_ANALYTICS_LIST_ROLLUP_PROPERTIESTool to list roll-up GA4 properties accessible to the caller. Use when you need to identify roll-up properties across all accessible accounts.1 params
Tool to list roll-up GA4 properties accessible to the caller. Use when you need to identify roll-up properties across all accessible accounts.
Parameters* required
pageSizeintegerOptional. Maximum number of account summaries to return; must be between 1 and 200.
GOOGLE_ANALYTICS_LIST_SEARCH_ADS360_LINKSTool to list all SearchAds360Links on a property. Use when you need to fetch all Search Ads 360 links for a given property after authenticating.3 params
Tool to list all SearchAds360Links on a property. Use when you need to fetch all Search Ads 360 links for a given property after authenticating.
Parameters* required
parentstringRequired. Resource name of the property. Format: properties/{propertyId} (e.g., properties/1234).
pageSizeintegerOptional. Maximum number of results to return. Must be between 1 and 200. Defaults to 50.
pageTokenstringOptional. Token for retrieving the next page of results.
GOOGLE_ANALYTICS_QUERY_AUDIENCE_EXPORTTool to query a completed audience export. Use when you need to fetch user rows with pagination.3 params
Tool to query a completed audience export. Use when you need to fetch user rows with pagination.
Parameters* required
namestringRequired. Resource name of the audience export. Format: properties/{property}/audienceExports/{audienceExport}.
limitintegerOptional. Number of rows to return. Must be between 1 and 250000. Defaults to 10000.
offsetintegerOptional. Zero-based start row index for pagination. Defaults to 0.
GOOGLE_ANALYTICS_QUERY_AUDIENCE_LISTTool to query an audience list. Use when you need to retrieve user rows from a GA4 audience list with pagination.3 params
Tool to query an audience list. Use when you need to retrieve user rows from a GA4 audience list with pagination.
Parameters* required
namestringRequired. Audience list resource to query. Format: properties/{property}/audienceLists/{audienceList}.
limitintegerOptional. Number of rows to return; default 10,000; maximum 250,000.
offsetintegerOptional. Zero-based row offset for pagination.
GOOGLE_ANALYTICS_RUN_FUNNEL_REPORTTool to run a GA4 funnel report. Use when you need a customized funnel analysis report for a given property.10 params
Tool to run a GA4 funnel report. Use when you need a customized funnel analysis report for a given property.
Parameters* required
limitintegerNumber of rows to return. Default 10000; max 250000.
funnelobjectFunnel configuration object following the API schema (must include 'steps').
propertystringGA4 property resource name, format: properties/{property_id}.
segmentsarrayUp to 4 segments; each yields its own row in the report.
dateRangesarrayList of date ranges to read; overlapping ranges duplicate days across ranges.
dimensionFilterobjectDimension-only filter expression.
funnelBreakdownobjectBreakdown dimension configuration for the funnel table sub-report.
funnelNextActionobjectNext-action dimension configuration for the funnel visualization sub-report.
returnPropertyQuotabooleanIf true, includes the property's current quota state.
funnelVisualizationTypestringVisualization type: STANDARD_FUNNEL (default) or TRENDED_FUNNEL.one of
STANDARD_FUNNEL · TRENDED_FUNNELGOOGLE_ANALYTICS_RUN_REPORTTool to run a customized GA4 data report. Use when you need event data after specifying dimensions, metrics, and date ranges.15 params
Tool to run a customized GA4 data report. Use when you need event data after specifying dimensions, metrics, and date ranges.
Parameters* required
limitintegerOptional. Number of rows to return. Must be between 1 and 250000.
offsetintegerOptional. 0-based start row for pagination. Must be >= 0.
metricsarrayOptional. The metrics to request and display. Each metric is an object with a 'name' field.
orderBysarrayOptional. Specify how rows are ordered. Each object defines dimension or metric ordering.
propertystringRequired. The property resource on which to run the report. Format: properties/{property_id}.
cohortSpecobjectOptional. Cohort specification. Requires requesting the cohort dimension.
dateRangesarrayOptional. The date ranges to read. Each range requires 'startDate' and 'endDate'.
dimensionsarrayOptional. The dimensions to request and display. Each dimension is an object with a 'name' field.
comparisonsarrayOptional. The comparison configuration. Adds a comparison column to the response.
currencyCodestringOptional. The currency code to apply, in ISO 4217 format. Defaults to property currency.
metricFilterobjectOptional. The filter expression to restrict metric values. Applied after aggregation.
keepEmptyRowsbooleanOptional. If true, rows with all zero metrics will be returned; otherwise omitted.
dimensionFilterobjectOptional. The filter expression to restrict dimension values. Only dimensions are allowed.
metricAggregationsarrayOptional. Aggregation types to include over metrics, e.g., 'TOTAL', 'MINIMUM', 'MAXIMUM'.
returnPropertyQuotabooleanOptional. If true, include the property's current quota state in the response.
Google Analytics 4 MCP Server
mcp-name: io.github.surendranb/google-analytics-mcp
Connect Google Analytics 4 data directly to AI agents, analyst copilots, and MCP runtimes across Claude, ChatGPT, Gemini, Cursor, VS Code, and OpenClaw. Gives models analysis-ready GA4 access with live schema discovery, metric auto-aliasing, server-side aggregation, and autonomous self-healing defenses.
🌐 Website & Documentation: https://ga4mcp.com
🔗 Sister Project: Google Search Console MCP
Powered by pypi.builditwithai.xyz
⚡ Quickstart — 1-Line Installations
1. Universal 1-Line Installer (Recommended)
Auto-detects your system, configures Gemini CLI, Claude Desktop, Cursor, and VS Code automatically in 1 command:
curl -fsSL https://ga4.builditwithai.xyz | bash
2. Homebrew (macOS & Linux)
brew tap surendranb/tap
brew install google-analytics-mcp
3. One-Click for Cursor
4. NPX / Node.js (Claude Code, Cursor, VS Code, Windsurf)
Add to your MCP configuration file (claude_desktop_config.json or .cursor/mcp.json):
{
"mcpServers": {
"ga4-analytics": {
"command": "npx",
"args": ["-y", "google-analytics-mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json",
"GA4_PROPERTY_ID": "123456789"
}
}
}
}
5. Gemini CLI Extension
Install directly into Google Gemini CLI with a single command:
gemini extensions install github.com/surendranb/google-analytics-mcp
6. Python uvx & Explicit python -m ga4_mcp
{
"mcpServers": {
"ga4-analytics": {
"command": "uvx",
"args": ["--from", "google-analytics-mcp", "ga4-mcp-server"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json",
"GA4_PROPERTY_ID": "123456789"
}
}
}
}
Or run directly via ga4-mcp-server / python -m ga4_mcp:
{
"mcpServers": {
"ga4-analytics": {
"command": "python",
"args": ["-m", "ga4_mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json",
"GA4_PROPERTY_ID": "123456789"
}
}
}
}
🧠 Why AI Agents & Marketers Prefer This Server
- Autonomous Self-Healing: System directives automatically intercept schema hallucinations (like guessing legacy metric names or incorrect filter nesting) and guide models to self-correct via
get_troubleshooting_guide. - Metric Auto-Aliasing: Automatically maps legacy or common LLM requests like
'conversions'→'keyEvents', preventing unnecessary query failures. - Server-Side Aggregation: Computes property totals dynamically for non-time-series queries, so LLMs spend time answering business questions rather than parsing raw rows.
- Data Volume Protection: Runs quick row-count estimates before executing large queries (>2,500 rows) to prevent crashing model context windows.
- Multi-Platform Support: Native packages and manifests for PyPI, npm, Gemini CLI, Smithery, OpenClaw, and OpenAPI REST actions.
🔑 Setup & Credentials Guide
1. Create a Google Cloud Service Account
- Open the Google Cloud Console.
- Enable the Google Analytics Data API.
- Under APIs & Services → Credentials, create a Service Account.
- Create a JSON Key and save it locally on your machine (e.g.
/Users/yourname/keys/ga4-key.json).
2. Grant Viewer Access in GA4
- Open Google Analytics.
- Select your GA4 Property → Open Admin (gear icon) → Property Access Management.
- Add the Service Account email (found inside the JSON key as
client_email) with the Viewer role.
3. Find Your GA4 Property ID
- In Google Analytics Admin → Property Details.
- Copy the numeric Property ID (e.g.,
123456789).
🛠️ Available Tools
| Tool Name | Purpose |
|---|---|
get_ga4_data | Execute GA4 queries with dimensions, metrics, date ranges, and optional filters. |
search_schema | Keyword search across 200+ GA4 dimension and metric API names. |
get_property_schema | Inspect all available dimensions and metrics for your specific property. |
list_metric_categories | Browse metric categories (User, Session, Revenue, Event). |
list_dimension_categories | Browse dimension categories (Geography, Traffic Source, Device). |
get_troubleshooting_guide | Self-healing guide for IAM permissions, setup, and filter syntax. |
🔒 Telemetry & Privacy
GA4 MCP collects anonymous usage telemetry to improve the server — no personal data, no GA4 report data, ever. Opt out anytime with DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1.
📄 License & Author
Developed by Surendran B under the Apache License 2.0.
Website: https://ga4mcp.com
Featured
Give your AI agent a complete email layer—sending, inbound inboxes, and sandbox testing.
Get 4K emails/month free →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →Capacitor makes coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Configuration
YOUR_API_KEY*secretYour API key for the service
Registryactive
Packagegoogle-analytics-mcp
TransportSTDIO
AuthRequired
UpdatedSep 9, 2025
