mcp-ga4

MCP server for Google Analytics 4 -- run reports, realtime data, custom dimensions, and property management via Claude.

Features

• 9 tools covering reporting, realtime data, custom dimensions/metrics, data streams, and feedback
• Two configuration modes: single-property (env vars) and multi-client (config.json)
• Supports both service account and OAuth credentials
• Relative date support (today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo)
• Built on official Google SDKs with resilience patterns

Installation

npm install mcp-ga4

Or clone the repository:

git clone https://github.com/mharnett/mcp-ga4.git
cd mcp-ga4
npm install
npm run build

Authentication

mcp-ga4 supports two credential families. Selection is deterministic and happens once, at startup: an explicit keyfile / service account wins, then user OAuth, and if neither is configured the server exits with a loud onboarding error naming both options. There is no machine-local credentials path baked into the code and no silent runtime failover -- the only credential inputs are environment variables and (optionally) your own per-user config.json. (A later 403 therefore surfaces as the API error, not as a silent switch to the other credential family.)

Precedence: when both families are configured, the keyfile / service account takes precedence over user OAuth.

Option A: Service account (recommended for unattended / server use)

Use this for any always-on or server deployment. Point GOOGLE_APPLICATION_CREDENTIALS (or config.json credentials_file) at a JSON keyfile. The service account must be granted access on the GA4 property (Admin → Property Access Management → add the service-account email with at least Viewer). No refresh token is involved -- the server hands the keyfile to the GA4 SDKs directly:

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

The keyfile may be a real service-account key or an authorized_user OAuth token dump -- both are accepted via the keyFile option.

Option B: User OAuth (personal / interactive use)

Use this if you want the server to act as a Google user (your own GA4 login). You bring your own Google OAuth client and mint a refresh token once.

1. In Google Cloud Console, create an OAuth 2.0 Client ID of type Desktop app. Enable the Google Analytics Data API (and the Admin API if you use the custom-dimension tools).

2. Export your client credentials and run the token helper (uses PKCE, opens a browser, prints the token to stdout):

   export GA4_CLIENT_ID=...            # from the Desktop-app client
   export GA4_CLIENT_SECRET=...
   node get-refresh-token.cjs          # or: npm run auth
   

   Do not redirect this command's stdout to a shared log -- the refresh token is printed there by design.

3. Copy the printed GA4_REFRESH_TOKEN=... into your environment. At runtime the server reads these three env vars:

   GA4_CLIENT_ID=...
   GA4_CLIENT_SECRET=...
   GA4_REFRESH_TOKEN=...
   

The scope requested is read from config.json oauth.scope (see below), so the helper and the running server never disagree on what you granted.

Scopes (minimum grant)

Scopes live in config.json under oauth.scope. The committed default is:

https://www.googleapis.com/auth/analytics.readonly
https://www.googleapis.com/auth/analytics.edit

analytics.edit is required because ga4_create_custom_dimension mutates the property via the Admin API. If you only need read access, override oauth.scope in your own config.json to analytics.readonly alone and re-run the helper.

Configuration

Security: Never share your .mcp.json file or commit it to git -- it may contain API credentials. Add .mcp.json to your .gitignore.

Mode 1: Single Property (env vars)

Set

... View full README on GitHub