{"id":"6ea37534-8322-4f5d-a690-9751c5b58192","slug":"google-analytics-agent","kind":"mcp","name":"google-analytics-agent","summary":"GA4 CLI and MCP server: data quality, configurable funnels, segment analysis, property management, and benchmarked Markdown audits.","owner":"arcbaslow","repoUrl":"https://github.com/arcbaslow/google-analytics-agent","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-05-20T19:09:42.000Z","addedAt":"2026-10-21T04:35:06.142Z","logoUrl":"https://avatars.githubusercontent.com/u/154324912?u=f788cf5aae102e80bb7678dd0520c784b98c6c6d&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["data-analytics","cloud-infra","developer-tools"],"tags":["ai-agent","analytics","attribution","claude-code","conversion-tracking","data-quality","event-tracking","funnel-analysis"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T06:09:24.654Z","sample":false,"url":"https://conduits.dev/tools/google-analytics-agent","language":"Python","transports":["stdio"],"install":{"pypi":"google-analytics-agent"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<p align=\"center\">\n  <img src=\"assets/banner.svg\" alt=\"Google Analytics Agent — GA4 data quality, funnels and property management.\" width=\"100%\">\n</p>\n\n# Google Analytics Agent\n\nGA4 data quality, funnels and property management.\n\n[![Tests](https://github.com/arcbaslow/google-analytics-agent/actions/workflows/tests.yml/badge.svg)](https://github.com/arcbaslow/google-analytics-agent/actions/workflows/tests.yml)\n[![Release](https://img.shields.io/github/v/release/arcbaslow/google-analytics-agent?color=d97706&label=release)](https://github.com/arcbaslow/google-analytics-agent/releases)\n[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-d97706?logo=python&logoColor=white)](#installation)\n[![MIT license](https://img.shields.io/badge/license-MIT-475569)](LICENSE)\n\n[Quick start](#quick-start) · [Example output](#example-output) · [Tests](#tests) · [Releases](#releases) · [Contributing](CONTRIBUTING.md)\n\nA Python CLI and MCP server for inspecting Google Analytics 4 properties. It combines the Data and Admin APIs with website context, configurable funnels, segment comparisons and benchmark annotations, then produces a prioritized audit report.\n\n## What you can do\n\n| Area | Included capabilities |\n| --- | --- |\n| Data quality | Sampling, missing values, event coverage, confidence labels, field discovery and Core compatibility checks |\n| Journeys | Ordered event funnels, cohort breakdowns and attribution analysis |\n| Context | Website, platform and vertical inference from the property's web stream |\n| Configuration | Streams, audiences, custom definitions, key events and event rules |\n| Reporting | Markdown, HTML and optional PDF audits; saved report and segment definitions |\n| Integration | Python adapters, `/ga4` skills and an MCP server with preview-first write tools |\n| Exploration | Uncached realtime, same-property group/date comparisons and alpha advertising conversion reports |\n| Export evidence | Optional BigQuery aggregate queries with dry-run defaults and byte caps |\n\n## Installation\n\nRequires **Python 3.10+**. For the source CLI:\n\nThe package requires Google Data client 0.18.16+ and Admin client 0.23.0+\n(both below 1.0). Reporting identity requires Admin 0.25.0+; older supported\nclients return `status: unsupported` for that read.\n\n```bash\ngit clone https://github.com/arcbaslow/google-analytics-agent.git\ncd google-analytics-agent\npython -m venv .venv\n```\n\nActivate with `source .venv/bin/activate` on macOS/Linux or `.venv\\Scripts\\Activate.ps1` in Windows PowerShell, then:\n\n```bash\npython -m pip install -e \".[dev]\"\n```\n\nFor just the published MCP package, use `python -m pip install \"google-analytics-agent[mcp]\"`. The **`[mcp]` extra is required** to run the server. PDF export uses the optional `[pdf]` extra and WeasyPrint system libraries; Markdown and HTML do not require them. See [setup](docs/SETUP.md).\n\n## Quick start\n\nLive queries require property access and Google credentials. The default path uses gcloud Application Default Credentials:\n\n```bash\npython scripts/ga4_auth.py --adc\n# Run the printed gcloud command, then:\npython scripts/ga4_auth.py --check\npython scripts/ga4_auth.py --properties\npython scripts/ga4_auth.py --quota-project YOUR_CLOUD_PROJECT_ID\n```\n\nUse a Cloud project with the Analytics Data and Admin APIs enabled. Replace the example property ID with one returned by `--properties`:\n\n```bash\npython scripts/ga4_audit.py --property 123456789 --days 28 --output audit.md\npython scripts/ga4_funnel.py --property 123456789 --steps sign_up,begin_checkout,purchase --days 28 --json\n```\n\nUse any ordered event list relevant to the property. The e-commerce funnel is also available as `--preset ecomm`. A Cloud OAuth desktop-client fallback is available through `ga4_auth.py --oauth --client-secret-file client.json`.\n\n## Example output\n\n![GA4 audit rendered from synthetic agent results](assets/screenshot.png)\n\nThis is the toolkit's Markdown report rendered for documentation, with **synthetic data**. Generate it without a property or credentials:\n\n```bash\npython scripts/ga4_report.py --property 123456789 --inputs examples/demo/quality.json,examples/demo/funnel.json --format md --confidence high --vertical ecommerce --output audit.md\n```\n\nInspect the [generated report](examples/demo/report.md) and [source fixtures](examples/demo/). The longer [sample audit](examples/sample-audit.md) is a separately authored illustration.\n\n## MCP server\n\nUse `ga4_data.py --property 123 --metadata --json` to discover report fields,\nor `--check-compatibility --metrics sessions --dimensions date --json` for\nan explicit Core compatibility check. MCP exposes these as `report_metadata`\nand `check_compatibility`. See [report fields](docs/REPORT_FIELDS.md).\n\nFor an MCP client that supports `mcpServers` configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"ga4\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"google-analytics-agent[mcp]\", \"ga4-mcp\"]\n    }\n  }\n}\n```\n\nAuthenticate on the machine running the server before querying it. `uvx` installs the available registry version; to run the current checkout, install `.[mcp]` and set the client's command to the absolute path of `.venv/bin/ga4-mcp` (or `.venv\\Scripts\\ga4-mcp.exe` on Windows).\n\nRead tools cover audits, reports, context, funnels, events, quality and property configuration. MCP write tools return previews. `confirm=true` cannot supply terminal approval. Use `propose_admin_write` to prepare an expiring, single-use proposal, then run its approval command yourself and answer `y/N`. See the [approval workflow](docs/APPROVALS.md) and [registered tools](scripts/ga4_mcp.py).\n\n## Everyday commands\n\n```bash\npython scripts/ga4_data.py --property 123456789 --report eventCount --dimensions eventName --days 28 --json\npython scripts/ga4_events.py --property 123456789 --list-events --days 7 --json\npython scripts/ga4_admin.py --property 123456789 --streams --json\npython scripts/ga4_admin.py --property 123456789 --key-events --json\npython scripts/ga4_definitions.py --list-segments\npython scripts/ga4_benchmarks.py --list-verticals\n```\n\nThe [router](skills/ga4/SKILL.md) provides `/ga4 audit`, `/ga4 funnel`, `/ga4 events`, `/ga4 audiences` and other agent commands. [AGENTS.md](AGENTS.md) documents the equivalent Python calls for other runtimes.\n\nAdditional adapters have separate, explicit contracts:\n\n- [Realtime and comparisons](docs/EXPLORATION.md): minute ranges or named groups/dates within one property.\n- [Advertising conversions](docs/ADVERTISING.md): alpha conversion-action metadata, models and report-section verification.\n- [BigQuery evidence](docs/BIGQUERY.md): optional `.[bigquery]` client; parameter, consent, freshness and funnel aggregates. Execution can incur query charges and requires `--execute` after a dry-run check.\n- [Annotations and history](docs/CHANGE_HISTORY.md): dated context, with private actor/snapshot fields omitted. History is a read that requires edit scope.\n- [Audience templates](docs/AUDIENCE_TEMPLATES.md): offline public-filter proposals; creation still requires separate approval.\n\n### Configuration writes\n\nAdmin writes require the appropriate property role and `analytics.edit` scope; print the sign-in command with `python scripts/ga4_auth.py --adc --write`. Every `ga4_admin.py` write prints the proposed change and asks `y/N` in an interactive terminal before any API call. Cancellation, EOF and piped input refuse the operation. There is no bypass flag; approve each write separately.\n\n### Interpreting an audit\n\nCacheable Data/Admin reads use a 15-minute cache isolated by resolved identity and scopes. Successful Admin writes invalidate all property queries; context has a separate 24-hour expiry. Explicit exploration, advertising, history and BigQuery reads are uncached. Responses pass through [PII scrubbing](scripts/ga4_utils.py), which cannot guarantee that every identifying value is removed. Partial reports expose `complete: false` and must not be presented as totals.\n\nThe bundled benchmark bands cover nine verticals. They are directional estimates stored in the repository, not live market measurements. Confidence labels describe the observed data-quality conditions; they do not establish causality. The audit supports arbitrary event journeys, although the legacy HTML template still uses an e-commerce heading.\n\n## Tests\n\n```bash\npython -m ruff check scripts/\npython -m ruff format --check scripts/\npython -m mypy\npython -m pytest scripts/ -q --cov=scripts --cov-report=term-missing --cov-fail-under=93\n```\n\nCI runs on Python 3.10–3.13 with a **93% production-only coverage floor**, excluding test modules. Minimum/current Analytics clients are checked separately. Tests use mocked transport and real SDK messages, plus synthetic in-memory SQL execution for BigQuery. They need no live GA4 property or BigQuery job. Offline integration tests do not establish live permissions, eligibility or API behavior. See the [verification record](docs/VERIFICATION.md).\n\n## Repository map\n\n| Path | Purpose |\n| --- | --- |\n| [scripts/](scripts/) | Data/Admin adapters, MCP server, report renderer and tests |\n| [agents/](agents/) · [skills/](skills/) | Specialist analysis and `/ga4` routing |\n| [examples/demo/](examples/demo/) | Synthetic report inputs and generated Markdown |\n| [docs/](docs/) | Setup, releases and verification |\n\n## Releases\n\n**[v0.5.2](https://github.com/arcbaslow/google-analytics-agent/releases/tag/v0.5.2)** — see the [release notes](docs/RELEASE_NOTES.md) for this release and the [changelog](CHANGELOG.md) for project history.\n\nGitHub Releases include downloadable artifacts and checksums. Package-registry publication is a separate, opt-in workflow; a GitHub release does not imply that the same version is available on PyPI or npm. Maintainers can follow the [release guide](docs/RELEASING.md).\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md), run the checks above, and include a minimal reproduction for bugs. Report vulnerabilities through [SECURITY.md](SECURITY.md).\n\n## Related tools\n\n| Project | Use it for |\n| --- | --- |\n| [Google Ads Agents](https://github.com/arcbaslow/google-ads-agents) | Paid media audits, tracking checks and reviewed changes. |\n| [Search Console Agent](https://github.com/arcbaslow/google-search-console-agent) | Search performance, indexing and page experience. |\n| [Meta Ads Agents](https://github.com/arcbaslow/meta-ads-agents) | Campaign performance, creative fatigue and event health. |\n| [GTM Diff](https://github.com/arcbaslow/gtm-diff) | Review the changes in your Google Tag Manager exports. |\n| [Figma Taxonomy Gen](https://github.com/arcbaslow/figma-taxonomy-gen) | Turn interactive designs into a reviewable tracking plan. |\n\nMaintained by [Good Labs](https://goodlabs.kz) — measurement implementation, tracking plans and analytics audits.\n\n## License\n\n[MIT](LICENSE) © Dilshat Rakhimov. This is an independent project; it is not an official product of the platform vendors.\n\nBenchmark tables and comparisons are labeled `source_status: unverified_heuristic`.\nTheir p25/p50/p75 names are legacy band labels, not verified population\npercentiles. Do not present them as evidence of industry performance or use\nthem alone to set severity. See [the source review](docs/ROADMAP.md).\n"}