ga-mcp-full

ga-mcp-full

A Model Context Protocol server that exposes the full Google Analytics 4 surface — both the Admin API (property & configuration management) and the Data API (reporting) — to MCP-compatible clients such as Claude Code, Claude Desktop, Cursor, Zed, and anything else that speaks stdio MCP.

Thirty-plus tools cover:

• Property management — create, list, update, delete, archive, retention settings
• Custom dimensions & metrics — create, list, update, archive
• Audiences — create, list, archive
• Key events — CRUD
• Data streams — CRUD
• Linked accounts — Firebase, BigQuery, Google Ads
• Measurement Protocol secrets — CRUD
• Reporting — standard reports, realtime reports, metadata discovery

Install

The preferred install is via the Robworks Claude Code Plugins marketplace:

pip install ga-mcp-full
claude plugin marketplace add ringo380/robworks-claude-code-plugins
claude plugin install ga-mcp-full@robworks-claude-code-plugins

Why a two-step install: the plugin just wraps the Python CLI — it does not bundle the Python interpreter. You install the CLI once (pip), then the plugin registers the MCP server, slash commands, and SessionStart hook with Claude Code.

Alternative: direct from the plugin repo

If you prefer to install the plugin directly from this repo without going through the Robworks marketplace:

pip install -e /path/to/ga-mcp-full
claude plugin marketplace add ringo380/ga-mcp-full   # uses the plugin repo as its own marketplace (once marketplace.json is added here)
claude plugin install ga-mcp-full

Note: this repo currently only ships a plugin.json, not a marketplace.json. Use the Robworks marketplace above as the install path.

Alternative: standalone MCP (no Claude Code plugin)

pip install -e /path/to/ga-mcp-full

Then add to your MCP client config. Example for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ga-mcp-full": {
      "command": "ga-mcp-full",
      "args": ["serve"]
    }
  }
}

For Cursor, Zed, or other clients, consult their MCP integration docs — the server command and arg pair is always ga-mcp-full serve.

Requirements

• Python 3.10 or newer
• Google Analytics 4 property you have Editor or Administrator access to (the OAuth flow requests analytics.edit for Admin API writes and analytics.readonly for Data API reporting)

That's it — no Google Cloud Console visit needed for the default install. A public Desktop OAuth client is bundled with the package.

Authentication

The server resolves credentials in this order (see ga_mcp/auth.py):

1. Cached OAuth tokens at ~/.config/ga-mcp/credentials.json. Refresh tokens renew expired access tokens silently.
2. Application Default Credentials — but only if the ADC token was actually granted the analytics.edit scope. A plain gcloud auth application-default login does not include this scope; you must run gcloud auth application-default login --scopes=https://www.googleapis.com/auth/analytics.edit. (Append ,https://www.googleapis.com/auth/analytics.readonly if you also want the reporting tools, which call the GA4 Data API and require the read-only scope.) If the scope is missing, resolution falls through with a clear error.

If neither source yields a working credential, the server surfaces a single actionable message telling you to run /ga-mcp-full:auth-login. The MCP server itself never opens a browser — the OAuth flow is driven by the CLI command (ga-mcp-full auth login) or its slash-command wrapper, since the MCP stdio subprocess has no attached terminal.

First-time setup (majority path)

1. Install: pip install ga-mcp-full (or pip install -e . for a dev checkout).
2. Run /ga-mcp-full:auth-login in Claude Code (or ga-mcp-full auth login at the shell).
3. Approve the requested scopes (analytics.edit + analytics.readonly) when the browser opens.
4. The refresh token lands in ~/.config/ga-mcp/credentials.json (mode 0600).

The OAuth flow uses PKCE (S256) and binds the loopback redirect to a random free port on 127.0.0.1, per Google's installed-app OAuth guidance. No prior Google Cloud Console client configuration is required.

You'll see an "unverified app" warning — this is expected for now