mcp-ga4

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

Quick install

Claude Code, one line (replace the placeholder values; see Authentication for a service account or user OAuth):

claude mcp add --env GA4_PROPERTY_ID=YOUR_PROPERTY_ID --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json --transport stdio ga4 -- npx -y mcp-ga4

For user OAuth instead of a service account, replace the credentials variable with GA4_CLIENT_ID, GA4_CLIENT_SECRET and GA4_REFRESH_TOKEN.

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), then fully quit and restart Claude Desktop:

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["-y", "mcp-ga4"],
      "env": {
        "GA4_PROPERTY_ID": "YOUR_PROPERTY_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

Add this to ~/.codex/config.toml:

[mcp_servers.ga4]
command = "npx"
args = ["-y", "mcp-ga4"]

[mcp_servers.ga4.env]
GA4_PROPERTY_ID = "YOUR_PROPERTY_ID"
GOOGLE_APPLICATION_CREDENTIALS = "/path/to/service-account.json"

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

Quick start

1. Get credentials -- a service-account keyfile, or a user-OAuth refresh token (see Authentication).

2. Register the server with every Claude client on this machine:

   # service account
   npx -p mcp-ga4 mcp-ga4-setup --property-id 123456789 --credentials /path/to/service-account.json
   
   # or user OAuth: export GA4_CLIENT_ID / GA4_CLIENT_SECRET / GA4_REFRESH_TOKEN first
   npx -p mcp-ga4 mcp-ga4-setup --property-id 123456789
   

   The wizard detects Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows) and the Claude Code CLI (claude on PATH) and registers ga4 with each one it finds. Other servers and settings in the Desktop config are preserved; an invalid config file is left untouched and the wizard stops. Re-running is safe. Use --claude-desktop-only or --claude-code-only to target one client.

3. Fully quit and reopen Claude Desktop (Cmd+Q), or restart your claude session.

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.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗