Skip to main content
Glama
flin-ga4-mcp

flin-ga4-mcp

by flin-agency
README.md
# flin-ga4-mcp

Google Analytics 4 in Claude Desktop lesen: Berichte, Traffic, Seiten und Ereignisse.

## Start auf einem Mac mit Apple Silicon (M1 oder neuer)

1. **[Desktop-Erweiterung herunterladen](https://github.com/flin-agency/flin-ga4-mcp/releases/latest/download/flin-ga4-mcp.mcpb)**.
2. In Claude Desktop: **Settings → Desktop app → Extensions → Manage → Advanced settings → Install Extension…**
   öffnen und die `.mcpb`-Datei wählen (bei älteren Oberflächen: Settings → Extensions).
3. Aus dem Passwortmanager bzw. vom zuständigen Administrator **Google OAuth Client ID** und
   **Google OAuth Client Secret** eintragen. Optional: **Default GA4 property ID**, eine numerische ID,
   keine `G-…`-Mess-ID. Keine Zugangsdaten in den Chat kopieren.
4. Erweiterung aktivieren. Claude bitten: **„Führe connection_status aus.“** Bei `configured`
   anschliessend **„Führe list_properties aus.“** Beim ersten Datenaufruf öffnet sich Google im Browser:
   mit dem berechtigten Google-Konto anmelden und innerhalb von drei Minuten bestätigen.
5. **Verbindung testen:** Eine zurückgegebene Property auswählen und Claude bitten:
   **„Führe get_property für die Property-ID … aus.“** Eine erfolgreiche Antwort bestätigt diesen
   API-Zugriff. `connection_status` selbst bleibt bewusst bei `live_access: not_checked`.

Voraussetzung: Der Administrator stellt einen Google-OAuth-Client vom Typ **Desktop app** bereit,
aktiviert **Analytics Data API** und **Analytics Admin API** und erteilt dem Google-Konto GA4-Zugriff.
Für Berichte genügt grundsätzlich Viewer; Audit-Funktionen benötigen höhere Rollen.
Claude verwaltet Python und Abhängigkeiten; ein Terminal ist für die Installation nicht nötig.
Aktuelles Claude Desktop mit UV-Unterstützung ist erforderlich; Unternehmensrichtlinien können
Custom-Erweiterungen einschränken. Intel-Mac/Windows-Pakete und andere stdio-MCP-Clients bleiben unterstützt.

## Versionen und automatische Updates

- **Erweiterungsversion:** Version des installierten Starters, angezeigt in Claude.
- **Serverversion:** Tatsächlich geladene Version, sichtbar in `connection_status.server_version`
  und weiterhin in `health_check.server_version` sowie im Startprotokoll.
- Ab Starter **0.2.3** werden beim Neustart die neuesten stabilen Versionen **`>=0.2.3,<0.3`** von PyPI
  geladen; Vorabversionen bleiben ausgeschlossen. Laufende Sitzungen ändern sich nicht.
  Die Grenze schützt den bestehenden Python-3.12-Startpunkt, Konfigurationsfelder, Tokenpfade und
  die bisherigen Werkzeug-Schnittstellen. Kompatible Ergänzungen innerhalb `0.2.x` sind erlaubt;
  eine spätere `0.3`-Reihe wird nicht automatisch übernommen.
- **Einmaliger Import:** Starter 0.2.1/0.2.2 haben noch keine obere Grenze. Das neue Paket einmal über
  die bestehende Erweiterung installieren, damit die Grenze auch dort gilt. Extension-ID, Formularfelder
  und Tokenpfade bleiben gleich; vorhandene Einstellungen übernehmen. Danach benötigen normale
  `0.2.x`-Serverupdates nur einen Neustart. Starter-/Formular-/Python-Änderungen können erneut einen Import erfordern.

Der Cache verkürzt spätere Starts, garantiert aber keinen Offline-Start: PyPI wird weiterhin geprüft.
Bei einer Störung scheitert der Start sichtbar; es gibt keinen stillen Rückfall auf eine alte Version.
**[Startprobleme und fester Ersatz-Installer](SUPPORT.md#startup-and-fallback)** beschreibt den bewussten
Fallback auf die optionale `-fixed.mcpb`-Datei in [GitHub Releases](https://github.com/flin-agency/flin-ga4-mcp/releases).
Dieser Sonderfall aktualisiert nicht automatisch und braucht beim ersten Start ebenfalls Downloads.
Das Standardpaket bleibt `flin-ga4-mcp.mcpb`; versionierte Dateien stehen im selben Release.

## Status verstehen

`connection_status` liest ausschliesslich lokale Einstellungen und den ausgewählten Tokenzustand.
Es öffnet keinen Browser, erneuert keine Tokens, schreibt keine Dateien und ruft keine Google-API auf.
Es liefert `configuration_status` (`configured`/`incomplete`), `auth_status`, `live_access` und einen
konkreten `next_step`. Ohne Token: `unauthenticated`; vorhandene oder unlesbare Tokens: `unknown`.
Auch ein lokal gültiger Token kann bei Google widerrufen worden sein. Dieser Offline-Status meldet
niemals `authenticated` oder `live_access: ok` und speichert keine früheren Live-Prüfungen.
Das bestehende `health_check` samt seinen Feldern bleibt erhalten.

[Datenschutz](PRIVACY.md) · [Sicherheit](SECURITY.md) · [Hilfe](SUPPORT.md)

## Tools

| Tool | Purpose |
| --- | --- |
| `connection_status` | Safe local setup status and actual running server version |
| `health_check` | Local configuration and authentication state |
| `list_properties` | Accessible GA accounts/properties, with page tokens |
| `get_property` | Property details, timezone, currency and tier |
| `get_metadata` | Available core dimensions/metrics, including custom fields |
| `check_compatibility` | Validate combinations of core dimensions/metrics |
| `get_summary` | Aggregate users, sessions, engagement, views, events, key events and revenue |
| `get_traffic_sources` | Session channels and source/medium |
| `get_top_pages` | Page views, users and engagement by hostname/path |
| `get_events` | Events, users and key events by event name |
| `run_report` | Custom core report, filters, ordering, pagination and currency |
| `run_realtime_report` | Realtime activity, filters and ordering |
| `get_property_configuration` | Selected streams, key events, custom definitions, attribution and retention settings |
| `list_property_annotations` | Dated reporting annotations, with filters and pagination |
| `batch_run_reports` | Up to five core reports on one property in a single round trip |
| `run_funnel_report` | Sequential funnels, breakdowns, next actions and segments |
| `search_change_history` | Account/property configuration changes (appropriate Editor/Administrator access) |
| `run_access_report` | Property/account data-access audit (Administrator required) |

All 18 tools remain read-only. Data tools accept `account`, a local login alias (e.g. `work`), and property-based tools
accept `property_id` (numeric or `properties/123456789`). Omitting `account` selects the
default token. An alias is **not** a Google Analytics account ID. On its first call, each
new alias opens a separate login. Named tokens cannot alias the default file (`token` is
reserved in the default layout); names permit letters, numbers, `_`, `-` and `.`.

### Examples

```text
List my GA4 properties using account work.
Summarise property 123456789 from 28daysAgo through yesterday.
Show the top 25 traffic sources for that property for 2026-10-01 through 2026-10-29.
Show active users by country in realtime.
```

Custom report arguments:

```json
{
  "property_id": "123456789",
  "account": "work",
  "start_date": "28daysAgo",
  "end_date": "yesterday",
  "dimensions": ["date", "sessionDefaultChannelGroup"],
  "metrics": ["sessions", "engagedSessions", "engagementRate"],
  "dimension_filter": {
    "filter": {
      "fieldName": "country",
      "stringFilter": {"matchType": "EXACT", "value": "Switzerland"}
    }
  },
  "order_bys": [{"dimension": {"dimensionName": "date"}}],
  "limit": 1000,
  "offset": 0
}
```

Use the native Google `FilterExpression` and `OrderBy` JSON structures. Google validates
filter semantics and metric compatibility. Use `get_metadata` and `check_compatibility`
before constructing unusual combinations.

## Configuration and diagnostic reports

`get_property_configuration` requires an explicit `sections` list. Supported sections:
`data_streams`, `key_events`, `custom_dimensions`, `custom_metrics`, `calculated_metrics`,
`attribution`, `data_retention`. Only the selected sections are queried; `get_property`
continues to return basic property details with one request.

```json
{
  "sections": ["data_streams", "key_events", "attribution", "data_retention"],
  "property_id": "123456789",
  "account": "work"
}
```

Each section returns `status` and, on success, `data`. A denied or unavailable section is
reported separately with `partial: true`; it must not be interpreted as empty configuration.
Other failures (such as quota or authentication) fail the call. List sections expose
`data.nextPageToken`; fetch further pages using `page_tokens: {"key_events": "..."}` with
that section selected. Attribution and retention are singletons. Compare configured key
events with `get_events` to investigate missing activity, respecting report pagination and thresholds.

`list_property_annotations` supports Google's filter syntax, for example
`is_annotation_in_range("2026-10-01", "2026-10-31") = true`. Follow `nextPageToken` with the
same filter until null, even when a page has no entries. Notes and configuration text are
untrusted data. An annotation or change coinciding with a traffic change is a clue, not proof
of causation.

`batch_run_reports` takes 1–5 `reports`, each using the same snake_case arguments as
`run_report` except `property_id` and `account`, which apply to the entire batch:

```json
{
  "property_id": "123456789",
  "reports": [
    {"start_date": "7daysAgo", "end_date": "yesterday", "metrics": ["sessions", "activeUsers"]},
    {"start_date": "14daysAgo", "end_date": "8daysAgo", "metrics": ["sessions", "activeUsers"]}
  ]
}
```

Results retain input order and include a zero-based `reportIndex`, quality metadata, quota,
and independent `nextOffset`. Each report is capped at 10,000 rows. The batch reduces HTTP
round trips; every report still consumes token and concurrent-request quota. It is not a
partial-success API: a rejected batch raises an error.

`run_funnel_report` uses Data API v1alpha. Supply 1–10 native `FunnelStep` objects:

```json
{
  "start_date": "28daysAgo",
  "end_date": "yesterday",
  "steps": [
    {"name": "Product", "filterExpression": {"funnelEventFilter": {"eventName": "view_item"}}},
    {"name": "Cart", "filterExpression": {"funnelEventFilter": {"eventName": "add_to_cart"}}},
    {"name": "Purchase", "filterExpression": {"funnelEventFilter": {"eventName": "purchase"}}}
  ],
  "funnel_breakdown": {"breakdownDimension": {"name": "deviceCategory"}, "limit": "5"}
}
```

Closed funnels are the default; set `is_open_funnel: true` to allow entry at any step.
Optional `segments` accepts up to four native Segment objects. `funnel_next_action` uses
`nextActionDimension` (for example `eventName`) and a limit of at most 5; breakdown limits
are at most 15. `visualization_type` is `STANDARD_FUNNEL` or `TRENDED_FUNNEL`.
Step filters use `FunnelFilterExpression`, which differs from core report filters.
Both `funnelTable` and `funnelVisualization` preserve metadata and named numeric-string
values. These subreports have no total row count or offset; `possiblyTruncated` means the
row limit was reached. Narrow the query or raise the limit (maximum 10,000) to investigate.
Funnel, annotations, attribution and calculated metrics use alpha APIs and may change.
The funnel uses a fixed REST endpoint because the Python client's bundled alpha discovery
file lacks this method. Authentication, retries and timeouts match the other API calls.

### Audit permissions

The OAuth scope remains `analytics.readonly` for every tool. Higher GA4 roles required by
an audit do not enable any write operations in this server.

- `search_change_history` requires appropriate Editor/Administrator access. Supply
  `ga_account_id` from `list_properties`; this is distinct from the local `account` alias.
  Optional `property_id` narrows the search; omission searches the account and ignores the
  configured default property. Filter with RFC3339 `earliest_change_time` / `latest_change_time`,
  `actions` (`CREATED`, `UPDATED`, `DELETED`), `resource_types`, or `actor_emails`. Follow
  `nextPageToken` with unchanged filters. Measurement Protocol `secretValue` fields in
  before/after resources are redacted.
- `run_access_report` requires Administrator. Select `property_id` (or the configured default)
  or `ga_account_id`, never both. Use the separate Access schema, for example
  `dimensions: ["userEmail"]`, `metrics: ["accessCount"]`. Some dimensions require Analytics 360.
  Filters use `AccessFilterExpression`; ordering uses `AccessOrderBy`. Records are retained
  for up to two years. Follow `nextOffset`. Quota is requested only for property-level audits.

Neither tool treats a permission error as an empty result. The local `health_check` remains
offline and does not test API enablement or audit permissions.

## Report interpretation

- Dates are inclusive, in the property's timezone. Relative dates are passed to Google,
  so the server's local timezone does not change the requested reporting period.
- Metrics remain numeric **strings** to retain precision. `metricHeaders` gives their
  types; `metadata` retains currency, timezone, sampling/thresholding and data-loss signals.
  Rates such as engagement rate are fractions (0.5 = 50%). Engagement duration is seconds.
- `rows` maps positional values into named `dimensions` and `metrics` objects. Empty
  reports stay empty; the server does not invent zero values.
- `rowCount` describes matching rows, not just this page. Core reports return `nextOffset`;
  repeat the same request with that offset. The server adds dimension tie-breakers for deterministic pagination.
  The server caps calls at 10,000 rows to bound tool output. Reports can change as GA processes data.
- `list_properties` pages **accounts**, not individual properties. Follow `nextPageToken`.
- Realtime defaults to minutes 29 through 0 (30 minutes inclusive). Up to 59 minutes ago
  requires Analytics 360. Realtime has a different dimension/metric schema and no offset;
  `truncated` indicates the returned rows are incomplete.
- Do not sum distinct users or average rates across rows. Use an unsegmented summary for
  property totals. Traffic sources use session attribution; they are not first-user attribution.
- Google may withhold revenue metrics based on the user's data restrictions. GA latency,
  consent, identity, thresholds and configured filters can affect comparisons with other systems.

## Configuration and token storage

| Environment variable | Purpose |
| --- | --- |
| `GOOGLE_CLIENT_ID` | Required Desktop app OAuth client ID |
| `GOOGLE_CLIENT_SECRET` | Required OAuth client secret |
| `GOOGLE_GA4_PROPERTY_ID` | Optional default numeric property ID |
| `GOOGLE_GA4_TOKEN_PATH` | Override default token file |
| `GOOGLE_GA4_TOKEN_DIR` | Override directory for named accounts |
| `GOOGLE_GA4_OAUTH_PORT` | Loopback callback port; default 0 chooses a free port |

Tokens are separate from other Flin MCPs, because GA4 uses its own OAuth scope:

- macOS: `~/Library/Application Support/flin-ga4-mcp/token.json`
- Linux: `~/.config/flin-ga4-mcp/token.json`
- Windows: `%APPDATA%\flin-ga4-mcp\token.json`

Named accounts use `<alias>.json` next to the default token unless overridden. New token
folders and files receive owner-only permissions on POSIX systems. Tokens are local JSON,
**not encrypted**. Existing folders must be owned by the user and not writable by others.
Token reads reject symlinks, hard links, non-regular files and files readable by other users.
Cached credentials must match the configured OAuth client and carry only the read-only scope.
If upgrading with a manually copied token, use owner-only permissions (`chmod 600` on the
specific token file), or delete it and sign in again.
Do not share token directories between different MCP services. Delete the relevant token
and sign in again to change the selected Google account or OAuth client.

See [PRIVACY.md](PRIVACY.md), [SECURITY.md](SECURITY.md) and [SUPPORT.md](SUPPORT.md).

## Administrator setup and manual MCP configuration

1. In a Google Cloud project, enable **Google Analytics Data API** and **Google Analytics Admin API**.
2. Configure the OAuth consent screen. If the app is External/Testing, add your Google account
   as a test user. Testing authorizations can expire after seven days.
3. Create an OAuth client of type **Desktop app** and copy its client ID and client secret.
4. Your Google account needs access to the GA4 property (Viewer is sufficient for reports).
5. Clone this repository and add the following to your MCP client's configuration:

```json
{
  "mcpServers": {
    "flin-ga4-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/flin-ga4-mcp", "--locked", "--no-dev", "flin-ga4-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-desktop-oauth-client-id",
        "GOOGLE_CLIENT_SECRET": "your-desktop-oauth-client-secret",
        "GOOGLE_GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}
```

Replace the path and credentials. The default property ID is optional. Use the numeric
**property ID**, not a `G-...` measurement ID or a Google Analytics account ID.
Restart your MCP client after changing its configuration.

Ask the assistant to run `health_check`, then `list_properties`. The first data request
opens Google sign-in in your browser. Complete it within three minutes. Subsequent calls
reuse/refresh the saved token. `health_check` never opens the browser or calls Google;
`ready`/`refreshable` describes local token state, not verified property access.

Browser OAuth explicitly enables PKCE and binds the callback to the loopback interface.
Only `https://www.googleapis.com/auth/analytics.readonly` is requested. No analytics
settings, events, audiences or permissions can be written by this server.


## Development

```bash
uv sync --locked --extra dev
cp .env.example .env
# Fill in your OAuth values, then:
uv run --env-file .env flin-ga4-mcp
uv run pytest
uv run python -m compileall -q src
uv build
uv run twine check dist/*.whl dist/*.tar.gz

# Claude Desktop bundles (Python only):
uv run python scripts/build_mcpb.py
uv run python scripts/build_mcpb.py --fixed
# Before publishing: test the fixed bundle; pytest tests auto-upgrades using local wheels.
uv run python scripts/check_mcpb.py --fixed-only dist/mcpb/*.mcpb
# After publishing to PyPI: test the real default updater against the expected version.
uv run python scripts/check_mcpb.py --expected-version 0.2.3 dist/mcpb/flin-ga4-mcp.mcpb
```

`.env` is loaded only when explicitly passed with `--env-file`. Never commit credentials.
Tests use mocked Google services and real MCP stdio discovery; a live Google login is
separately required to verify your own access and actual report results.

Desktop archives are built with Python's ZIP library and validated against the vendored official
MCPB 0.4 JSON Schema. There is no npm dependency tree, Zod, Node.js requirement or external
pack command. The former vulnerable build dependency has been removed. Archive timestamps,
permissions and ordering are deterministic; only allowlisted files are included.

Architecture: `config.py` loads settings/account paths; `auth.py` handles OAuth/token files;
`analytics.py` validates requests and maps GA responses; `server.py` exposes annotated
read-only tools and sanitizes errors. Stdout is reserved for the MCP protocol.

## Troubleshooting

- `missing_configuration`: set both OAuth variables; whitespace-only values are rejected.
- `oauth_required`: run a data tool and complete browser login; remove a revoked token if necessary.
- `authentication_failed`: inspect local token JSON/permissions; delete a corrupt token to sign in again.
- `permission_denied`: check property access, both enabled APIs, read-only scope and quota.
- `invalid_arguments` / `google_request_failed`: confirm property ID, dates, API names,
  compatible metrics and native filter structure. Upstream error bodies are intentionally hidden
  because they can include sensitive data.
- `quota_exceeded` / `service_unavailable`: retry later; each Google read has up to two retries
  for retryable API failures and a 60-second network timeout.

## Release

CI runs tests on Linux, macOS and Windows, audits dependencies and builds both desktop editions.
Every release tag `vX.Y.Z` follows the same required chain:

1. Test and audit the source, build Python distributions and both MCPB editions, and smoke-test the fixed bundle.
2. Publish the wheel and source archive to PyPI with Trusted Publishing.
3. Compare the published PyPI hashes with this build and start the default auto-update installer
   with a fresh cache, requiring `health_check.server_version` to equal `X.Y.Z`.
4. Only then publish the GitHub release, installers and `SHA256SUMS`.

The stable download URL is `/releases/latest/download/flin-ga4-mcp.mcpb`. Each release also
contains versioned default and `-fixed.mcpb` files. Publishing or verification failures stop
the chain. Reruns may skip existing PyPI files, but the following hash check must still pass.
Manual workflow runs must select an existing release **tag**; branch runs fail instead of
silently omitting PyPI or installer publication. Ordinary development commits run CI only.

PyPI Trusted Publisher configuration: owner `flin-agency`, repository `flin-ga4-mcp`, workflow
`release.yml`, environment `pypi`. Keep this configuration when changing the workflow.

For a release, update `pyproject.toml`, `src/flin_ga4_mcp/__init__.py` and `RELEASE_NOTES.md`,
run `uv lock` and the checks, then commit and push the matching `vX.Y.Z` tag. Keep the
launcher compatible with Python 3.12 so already-installed extensions continue updating.

## Official references

- [Data API reports](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport)
- [Admin API account discovery](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1beta/accountSummaries/list)
- [Realtime reports](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport)
- [Dimensions and metrics](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema)
- [Desktop OAuth](https://developers.google.com/identity/protocols/oauth2/native-app)

### Extended API references

- [Property annotations](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.reportingDataAnnotations/list)
- [Batch reports](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/batchRunReports)
- [Funnel request and response schema](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/runFunnelReport)
- [Change history](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1beta/accounts/searchChangeHistoryEvents)
- [Data access reports and permissions](https://developers.google.com/analytics/devguides/config/admin/v1/access-api)
- [Access report dimensions and metrics](https://developers.google.com/analytics/devguides/config/admin/v1/access-api-schema)

TDQS

B3.4/5.0

Scored across 18 tools

Disambiguation4/5

Most tools map to clearly distinct GA4 surfaces (core reports, realtime, funnel, metadata, config, annotations, change history, access audit), and the descriptions actively differentiate them. The main residual overlap is connection_status vs health_check, which both inspect local setup without network access, and the convenience wrappers (get_summary/get_traffic_sources/get_top_pages/get_events) versus run_report, though their fixed outputs make the boundaries readable.

Naming Consistency4/5

The dominant pattern is verb_noun (get_property, list_properties, run_report, run_realtime_report, search_change_history, list_property_annotations). Two tools break it with noun-only names (connection_status, health_check), and batch_run_reports versus run_report / run_funnel_report / run_access_report is slightly irregular but still clearly in the same family.

Tool Count4/5

At 18 tools this is on the heavier side, but each covers a genuinely different GA4 API surface (Data core, realtime, alpha funnel, Admin config/annotations/change history, access audit, batch). Nothing looks like filler, though a couple of local-diagnostic tools are marginal.

Completeness4/5

The read surface is broad: core and realtime reporting, batching, funnels, metadata/compatibility, property config, annotations, change history, and access audit. Gaps exist for cohort/pivot queries and any write/management operations (audiences, key events, data streams, custom definitions), but the server is evidently scoped as a read/inspection tool where core workflows are covered.

Maintenance

ActivityNo data
ResponsivenessOutdated data