ga4-firebase-mcp
# ga4-firebase-mcp
MCP server for Google Analytics 4, including the Analytics of Firebase projects. 36 tools: configuration that is remembered across sessions, Firebase lookups, Data API reports (custom reports, realtime, pivots, period comparison, funnels, cohorts, active users, acquisition) and Admin API settings. Every tool states which Google API, GA4 role and scope it needs; access errors come back with the exact steps to fix them, and `ga4_check_access` checks everything at once.
- [docs/HERRAMIENTAS.md](docs/HERRAMIENTAS.md): every tool, its parameters, dimensions and metrics.
- [docs/DIMENSIONES.md](docs/DIMENSIONES.md): every dimension and metric of the property, generated from its metadata.
## Install from npm
```bash
npx -y -p ga4-firebase-mcp ga4-firebase-mcp-setup --firebase-project <firebase-project-id>
```
That registers the server in Claude Code as `npx -y ga4-firebase-mcp`, checks your Google credentials and saves the property. It takes the same options as `npm run setup` (below). To register only the server:
```bash
claude mcp add ga4 -s user -- npx -y ga4-firebase-mcp
```
Requirements: Node 18+, and for credentials either [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) (`gcloud auth application-default login`) or a service account JSON. Your Google account needs at least Viewer access to the GA4 property.
## Setup from source
Easiest: open Claude Code in this folder and say "instala este MCP". `CLAUDE.md` tells the agent what to ask and what to run.
By hand, one command does everything (dependencies, build, Claude Code registration, Google credentials check, and optionally saving a property). It is safe to re-run:
```bash
npm run setup -- --firebase-project <firebase-project-id>
```
Options: `--property-id <id> --quota-project <gcp-project>` instead of a Firebase project; `--key-file <json>` for a service account; `--login` to run the Google sign-in if it's missing (opens a browser); `--write` to include write access (create custom dimensions); `--name` / `--scope` for the Claude Code registration. Exit code 0 means ready, 2 means the user must do something (shown with `→`), and 1 means an error, with the explanation.
To share it, copy the folder without `node_modules` and `dist`; the installer uses its own path, so it works from any location.
Then, from any Claude session, configure a property in plain words, e.g. "configura GA4 con el proyecto de Firebase mi-proyecto-firebase". That calls `ga4_configure`, tests the connection and saves it to `~/.config/ga4-mcp/config.json` (mode 600; override with `GA4_MCP_CONFIG`).
Authentication per property: Application Default Credentials (`gcloud auth application-default login`), a credentials JSON file (service account or authorized user), or a raw access token.
`GA4_PROPERTIES` / `GA4_PROPERTY_ID` / `GA4_QUOTA_PROJECT` environment variables still work as read-only properties.
## Regenerate the dimensions reference
```bash
npm run build
npm run docs:dimensions -- <property-name>
```
## License
MIT. See [LICENSE](LICENSE).
TDQS
Scored across 36 tools
Most tools target clearly distinct GA4 surfaces (top events vs. realtime vs. pivot vs. batch reports; custom dimensions vs. custom metrics; list vs. create dimension). A few pairs are genuinely close — ga4_top_events vs. ga4_event_counts, ga4_funnel vs. ga4_step_conversion, ga4_check_access vs. ga4_test_connection, and the three Firebase tools (property_from_firebase / firebase_apps / firebase_links) — but the descriptions explicitly cross-reference and differentiate them, which mitigates the risk.
All 36 tools share a uniform ga4_ prefix and snake_case, so the family is immediately recognizable. Most names are noun-phrase report/resource names (ga4_active_users, ga4_audiences, ga4_data_streams) while a handful use verb_noun (ga4_create_custom_dimension, ga4_list_properties, ga4_run_report, ga4_configure); the mix is readable but not a single strict verb_noun pattern.
36 tools is heavy for one server and well past the comfortable 3-15 range, partly because many convenience wrappers (top_events, event_counts, active_users, acquisition, tech_breakdown, screen_views, cohort_retention, compare_periods, step_conversion) are thin specializations of ga4_run_report. The breadth of GA4 Data + Admin + Firebase + connection-management domains justifies a large surface, but consolidation would make selection easier.
Reporting coverage is excellent — generic, batch, pivot, realtime, funnel, cohort, and many prebuilt reports — and admin read coverage spans properties, streams, audiences, key events, links, retention, and change history. The main gap is write/CRUD depth: only custom dimension creation exists, with no update/delete of dimensions, key events, or streams, though connection setup, access diagnostics, and metadata discovery are all present.