{
"markdown": "# google-analytics-mcp-server\n\n[](https://github.com/getmcpads-com/google-analytics-mcp-server/actions/workflows/ci.yml)\n[](LICENSE)\n[](package.json)\n\nAn open-source [Model Context Protocol](https://modelcontextprotocol.io) server for\n**Google Analytics 4**. It lets Claude, ChatGPT, Cursor or any MCP client query your\nanalytics data and inspect how your property is configured.\n\n**Read-only, with no way to turn that off.** You run it, and your credentials stay on your\nmachine.\n\n```bash\nnpx -y @getmcpads/google-analytics-mcp-server\n```\n\nAlso listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as **`com.getmcpads/google-analytics`**, so clients that read the registry can install it by name.\n\n> **Prefer not to run it yourself?** [getmcpads.com](https://www.getmcpads.com) is the hosted\n> version of this server, with Google Analytics alongside Meta Ads, Google Ads, TikTok Ads,\n> Pinterest Ads and Search Console behind a single endpoint, hosted OAuth, and cross-platform\n> reporting. Same tools, same safety model, no setup.\n\n---\n\n## What you get\n\n| | |\n|---|---|\n| **27 read tools** | Reports, pivots, funnels, realtime, plus the Admin API: properties, data streams, custom definitions, key events, audiences |\n| **Diagnostics** | Ecommerce, BigQuery export, server-side tagging, audience exports, quota snapshots |\n| **51 metrics, 62 dimensions** | With a compatibility matrix that catches invalid combinations before they hit the API |\n| **6 resources** | Live catalogues the model can read: metrics, dimensions, compatibility rules, 12 workflow recipes |\n| **Identifier redaction** | User, email and device identifiers redacted by default on access bindings and audience exports, with explicit opt-in to see them |\n| **No writes at all** | Not a flag, a property of the code. See below |\n\n### Compatibility, checked before the call\n\nGA4 rejects many metric and dimension combinations, and its errors rarely explain which pair\nis at fault. This server carries the compatibility matrix, so `ga4_check_compatibility` and\n`ga4_validate_query` let the model verify a combination before spending a call and a quota\ntoken on it.\n\nQuotas matter here more than on ad platforms: GA4 charges tokens per property per day, and a\nfew careless exploratory queries can exhaust them. `ga4_get_property_quotas_snapshot` shows\nwhat is left.\n\n---\n\n## How this compares to Google's own MCP server\n\nThe Google Analytics team ships an official MCP server, and it is good. It is Apache-2.0,\nruns locally, is read-only, and has a large community. Be clear about what differs.\n\n| | **This server** | Google's official server | [getmcpads.com](https://www.getmcpads.com) |\n|---|---|---|---|\n| Tools | **27** | 7 | 27, plus 5 other platforms |\n| Hosting | **Local**, via npx | Local, via pipx | Hosted for you |\n| Read-only | **Yes** | Yes | Yes |\n| Reports | Their three, plus **pivots, batch reports, advanced funnels** | `run_report`, `run_funnel_report`, realtime | Same |\n| Admin API | **Broader**: data streams, key events, channel groups, audiences, audience exports | Account summaries, property details, custom definitions | Same |\n| Diagnostics | **Ecommerce, BigQuery export, server-side tagging, quotas** | None | Same |\n| Metric compatibility | **Catalogue and matrix, checkable before the call** | None | Same |\n| Identifier redaction | **Default on, opt-in to disable** | None | Same |\n| Language | TypeScript | Python | |\n| Status | 1.0 | Labelled experimental by Google | |\n\n**Neither is more private than the other.** Both run locally and read only. If the seven\nofficial tools cover what you need, and your model writes clean GA4 report requests, use\nGoogle's: it is maintained by the team that owns the API.\n\n**Choose this one** when you want named metrics validated against a compatibility matrix\nrather than raw request bodies, when you need the configuration and diagnostics surface, or\nwhen you want identifiers redacted by default rather than by discipline.\n**Choose [getmcpads.com](https://www.getmcpads.com)** if you want this server's capabilities\nwithout running it, or you need analytics and ad platforms in the same conversation.\n\n---\n\n## Read-only, and why it stays that way\n\nThere are no write tools, and no environment variable that adds any. Every tool calls a read\nmethod of the Data API or the Admin API.\n\nThis is not caution for its own sake. A misread report is a wrong answer you can spot. A\nmistaken write to an analytics property, a deleted audience or an edited data stream, corrupts\nthe record you use to judge everything else, and often silently. The other servers we publish\ndo have write tools, guarded by a mandatory preview. This one has none.\n\nOur ad platform servers with guarded writes:\n[Meta Ads](https://github.com/getmcpads-com/meta-ads-mcp-server) Ā·\n[Google Ads](https://github.com/getmcpads-com/google-ads-mcp-server) Ā·\n[TikTok Ads](https://github.com/getmcpads-com/tiktok-ads-mcp-server)\n\n---\n\n## Personal data\n\nAnalytics data is not anonymous by default. A GA4 property can carry a `userId` you set\nyourself, a device identifier, or a Google Signals pseudonymous ID. An MCP conversation sends\nwhatever a tool returns to a model.\n\n**Identifiers are redacted by default wherever this server can return them**, and showing them\nis an explicit opt-in, never the default.\n\n| Tool | Behaviour |\n|---|---|\n| `ga4_list_admin_resources` | Access bindings have user and email identifiers redacted |\n| `ga4_query_audience_export` | Identifier columns redacted, matched against the export's own dimension metadata |\n| `ga4_get_audience_export_diagnostics` | Same redaction on the row sample |\n\nEvery one of these accepts `includePersonalIdentifiers: true` to return raw values, and\ndefaults to `false`.\n\nAudience export rows are positional, so the redaction reads the export's dimension metadata to\nfind identifier columns. **If that metadata is missing, every value in the row is redacted**\nrather than guessing which column is safe. Failing closed is the point.\n\n**Report rows are not redacted.** `ga4_run_report` and the other reporting tools return what\nyou asked for. Altering the numbers a report returns would be worse than returning them.\n\nSo one decision stays yours: if your property carries a `userId` you consider personal, do not\nrequest it as a report dimension in a conversation whose transcript leaves your machine.\n\n---\n\n## Getting credentials\n\nThree values, obtained once.\n\n### 1. OAuth client\n\nIn a [Google Cloud project](https://console.cloud.google.com/), enable the **Google Analytics\nData API** and the **Google Analytics Admin API**, then create an OAuth client under\n**APIs & Services ā Credentials**. Choose **Desktop app** for local use. Note the **client ID**\nand **client secret**.\n\n### 2. Refresh token\n\nRun the OAuth consent flow once, signed in as a Google account with access to your GA4\nproperties, and keep the **refresh token**. The `analytics.readonly` scope is enough, and it\nis the only one you should grant.\n\nš [Google OAuth for installed apps](https://developers.google.com/identity/protocols/oauth2/native-app)\n\n**The refresh token does not expire.** It is the sensitive value: anyone holding it can mint\naccess tokens indefinitely. Use an OAuth client dedicated to this server so you can revoke it\non its own.\n\n### 3. Property ID, optional\n\nSet `GA4_PROPERTY_ID` to avoid passing it on every call. Find it in GA4 under\n**Admin ā Property Settings**, or list them with `ga4_list_properties`.\n\nRun **`ga4_health_check`** as your first call. It verifies the credentials and lists the\nproperties you can actually reach, without printing any secret.\n\n---\n\n## Setup\n\n### Claude Desktop\n\n`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\nor `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n \"mcpServers\": {\n \"google-analytics\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@getmcpads/google-analytics-mcp-server\"],\n \"env\": {\n \"GA4_CLIENT_ID\": \"your-client-id\",\n \"GA4_CLIENT_SECRET\": \"your-client-secret\",\n \"GA4_REFRESH_TOKEN\": \"your-refresh-token\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop. Ask it: *\"list my Google Analytics properties\"*.\n\n### Claude Code\n\n```bash\nclaude mcp add google-analytics --env GA4_CLIENT_ID=... --env GA4_CLIENT_SECRET=... --env GA4_REFRESH_TOKEN=... -- npx -y @getmcpads/google-analytics-mcp-server\n```\n\n### Cursor\n\n`.cursor/mcp.json` in your project, same shape as the Claude Desktop config above.\n\n### From source\n\n```bash\ngit clone https://github.com/getmcpads-com/google-analytics-mcp-server.git\ncd google-analytics-mcp-server\nnpm install && npm run build\ncp .env.example .env # then fill in your credentials\nnpm start\n```\n\n### Configuration\n\n| Variable | Default | Meaning |\n|---|---|---|\n| `GA4_CLIENT_ID` | none | **Required.** OAuth client ID |\n| `GA4_CLIENT_SECRET` | none | **Required.** OAuth client secret |\n| `GA4_REFRESH_TOKEN` | none | **Required.** From the consent flow |\n| `GA4_PROPERTY_ID` | none | Optional default, saves passing it on every call |\n| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |\n\nCheck your setup at any time:\n\n```bash\nnpm run doctor\n```\n\n---\n\n## Tools\n\n\n27 read tools
\n\n### Discovery and health\n| Tool | Purpose |\n|---|---|\n| `ga4_health_check` | Validates credentials and lists reachable properties |\n| `ga4_list_accounts` / `ga4_list_properties` | Accounts and properties you can reach |\n| `ga4_get_property_configuration` | Timezone, currency, industry, data retention |\n| `ga4_get_metadata` | Metrics and dimensions available on a given property |\n\n### Reporting\n| Tool | Purpose |\n|---|---|\n| `ga4_run_report` | The main reporting tool. Named metrics and dimensions |\n| `ga4_run_pivot_report` | Pivot tables |\n| `ga4_batch_run_reports` / `ga4_batch_run_pivot_reports` | Several reports in one call |\n| `ga4_run_realtime_report` | The last 30 minutes |\n| `ga4_run_advanced_funnel_report` | Funnel analysis with step conditions |\n| `ga4_run_funnel_recipe` | Prebuilt funnels for common journeys |\n| `ga4_validate_query` / `ga4_check_compatibility` | Check a combination *before* running it |\n\n### Configuration\n| Tool | Purpose |\n|---|---|\n| `ga4_list_admin_resources` | Data streams, users, links. Access-binding identifiers redacted |\n| `ga4_get_custom_definitions` | Custom dimensions and metrics |\n| `ga4_get_key_events` | Key events and their counting method |\n| `ga4_get_channel_groups` | Default and custom channel groupings |\n| `ga4_get_event_parameters` | Parameters actually collected on an event |\n\n### Audiences\n| Tool | Purpose |\n|---|---|\n| `ga4_get_audience_diagnostics` | Audience definitions and their health |\n| `ga4_list_audience_exports` / `ga4_query_audience_export` | Audience exports and their rows |\n| `ga4_get_audience_export_diagnostics` | Why an export is empty or stale |\n\n### Diagnostics\n| Tool | Purpose |\n|---|---|\n| `ga4_get_ecommerce_diagnostics` | Whether ecommerce events are complete and coherent |\n| `ga4_get_bigquery_export_diagnostics` | BigQuery export configuration and freshness |\n| `ga4_get_server_side_tagging_diagnostics` | Server-side tagging signals |\n| `ga4_get_property_quotas_snapshot` | Remaining Data API quota tokens |\n\n \n\n\n6 resources
\n\n| URI | Contents |\n|---|---|\n| `ga4://manifest` | What this server exposes, and which tool to run first |\n| `ga4://metrics` | All 51 metrics with categories and formats |\n| `ga4://dimensions` | All 62 dimensions and where they are valid |\n| `ga4://compatibility` | The compatibility matrix |\n| `ga4://recipes` | 12 step-by-step workflows |\n| `ga4://p2-diagnostics` | Diagnostic playbooks |\n\n \n\n---\n\n## Security\n\n- **The client secret and refresh token are never logged**, at any log level, or written to disk.\n- **Three hosts are contacted, and only three**: `analyticsdata.googleapis.com`,\n `analyticsadmin.googleapis.com` and `oauth2.googleapis.com`. *A test fails the build if a\n fourth host appears in the source.*\n- **No fetch follows a redirect.** Every outbound call sets `redirect: \"error\"`, so a redirect\n cannot forward a bearer token or client secret to another host. *A test fails the build if\n any fetch omits this.*\n- **No telemetry.** The server makes no network call other than to Google.\n\nFull policy, including how personal data is handled: [SECURITY.md](SECURITY.md).\n\n---\n\n## Looking for a managed, multi-platform version?\n\nThis server does one platform, on your machine, with your credentials. That is on purpose.\n\nIf you'd rather not run it yourself, or you need Google Analytics **alongside Meta Ads, Google\nAds, TikTok Ads, Pinterest Ads and Search Console** behind one endpoint, with hosted OAuth and\ncross-platform reporting, that's what we build at **[getmcpads.com](https://www.getmcpads.com)**.\n\nSame philosophy, less plumbing. This project stays open source and independently useful\neither way.\n\n---\n\n## Contributing\n\nIssues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).\nPlease read [SECURITY.md](SECURITY.md) before reporting anything security-related.\n\n## Licence\n\n[Apache License 2.0](LICENSE). See also [NOTICE](NOTICE).\n\nGoogle, Google Analytics and GA4 are trademarks of Google LLC.\n**This project is not affiliated with, endorsed by, or sponsored by Google LLC.**\nIt is an independent client of a public API.\n",
"bytes": 13656,
"sha": "0423112bfc2406b46fb81eb951cec3206cae01a555111072455d44299b764290",
"repo_slug": "getmcpads-com/google-analytics-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_com_getmcpads_google_analytics_66b49203/readme"
}