Metadata-Version: 2.4
Name: ga-mcp-full
Version: 0.5.1
Summary: GA4 MCP server with full Admin API read/write access
Author: Ryan Robson
License-Expression: MIT
Project-URL: Homepage, https://github.com/ringo380/ga-mcp-full
Project-URL: Repository, https://github.com/ringo380/ga-mcp-full
Project-URL: Issues, https://github.com/ringo380/ga-mcp-full/issues
Project-URL: Privacy Policy, https://github.com/ringo380/ga-mcp-full/blob/main/PRIVACY.md
Keywords: google-analytics,ga4,mcp,claude-code,analytics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-analytics-data==0.21.0
Requires-Dist: google-analytics-admin==0.28.0
Requires-Dist: google-auth~=2.40
Requires-Dist: google-auth-oauthlib~=1.2
Requires-Dist: mcp>=1.24.0
Requires-Dist: google-adk>=1.24.1
Requires-Dist: httpx>=0.28.1
Dynamic: license-file

# ga-mcp-full

[![PyPI version](https://img.shields.io/pypi/v/ga-mcp-full.svg)](https://pypi.org/project/ga-mcp-full/)
[![Python versions](https://img.shields.io/pypi/pyversions/ga-mcp-full.svg)](https://pypi.org/project/ga-mcp-full/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Release to PyPI](https://github.com/ringo380/ga-mcp-full/actions/workflows/release.yml/badge.svg)](https://github.com/ringo380/ga-mcp-full/actions/workflows/release.yml)

A [Model Context Protocol](https://modelcontextprotocol.io/) 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](https://claude.com/product/claude-code), [Claude Desktop](https://claude.ai/download), 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:

```bash
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:

```bash
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)

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

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

```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

The bundled OAuth client is a real production app owned by this project, but Google's brand verification for sensitive scopes (like `analytics.edit`) takes several business days the first time. Until verification clears, the consent screen displays:

> Google hasn't verified this app
> The app is requesting access to sensitive info in your Google Account…

To proceed: click **Advanced** → **Go to ga-mcp-full (unsafe)**. The warning is Google's default posture for unverified apps — it doesn't indicate anything is actually wrong with the tool. Review the [privacy policy](./PRIVACY.md) if you want to know exactly what data is accessed (it's all local, per-user, per the scope you approved). The warning will disappear once Google's review completes.

Users who want to avoid the warning entirely can use their own OAuth client — see **Power users** below.

### Power users: use your own OAuth client

If you want quota isolation, a custom consent screen, or to avoid the verification-window warning:

1. Create an **OAuth 2.0 Client ID** of type **Desktop app** at **Google Cloud Console → APIs & Services → Credentials** in a project where the Google Analytics Admin API and Data API are enabled.
2. Override the bundled defaults via either:
   - Env vars in your shell profile: `GA_MCP_CLIENT_ID=...` and `GA_MCP_CLIENT_SECRET=...`
   - Or drop the downloaded JSON at `~/.config/ga-mcp/client_secrets.json` (mode `0600`).
3. Run `ga-mcp-full auth login` as usual — the env vars / legacy JSON take precedence over the bundled client.

### Already using `gcloud`?

If you have `gcloud auth application-default login --scopes=https://www.googleapis.com/auth/analytics.edit,https://www.googleapis.com/auth/analytics.readonly` configured, the server auto-detects ADC and skips OAuth entirely. No further setup needed. (The `analytics.readonly` scope is only needed for the reporting tools; `analytics.edit` alone is enough for the Admin API.)

### Why not the `/mcp` Authenticate button?

Claude Code's `/mcp` menu OAuth flow only applies to **HTTP-transport** MCP servers per the MCP 2025-06-18 authorization spec (stdio servers "SHOULD NOT" use it). `ga-mcp-full` is stdio, so auth is handled out-of-band via the bundled slash commands and the SessionStart hook. An HTTP transport mode that participates in the `/mcp` OAuth flow is a possible future addition.

## Bundled Claude Code components

### Slash commands

| Command | Purpose |
| --- | --- |
| `/ga-mcp-full:setup` | Guided first-run — install the CLI (if needed) and run the browser login |
| `/ga-mcp-full:auth-login` | Run the OAuth browser flow and cache tokens |
| `/ga-mcp-full:auth-logout` | Remove cached OAuth credentials |
| `/ga-mcp-full:auth-status` | Show current auth state and credential source |

### SessionStart hook

`hooks/scripts/ensure-auth.sh` runs at the start of every Claude Code session (`startup|resume|clear|compact`). It is non-blocking and only writes to stderr — if the CLI is installed but unauthenticated, it prints a one-line hint pointing at `/ga-mcp-full:auth-login`; if the CLI is not on `PATH` at all, it points at `pip install ga-mcp-full`. It never exits non-zero and never blocks the session.

### MCP tools

After plugin install the server registers as `plugin:ga-mcp-full:ga-mcp-full` and tools surface as `mcp__ga-mcp-full__*`. Browse them with `/mcp` inside Claude Code.

## CLI reference

```bash
ga-mcp-full                 # Start the MCP server over stdio
ga-mcp-full serve           # Same as above (explicit)
ga-mcp-full auth login      # OAuth browser flow; caches refresh token
ga-mcp-full auth logout     # Clear cached credentials
ga-mcp-full auth status     # Show current auth state and credential source
ga-mcp-full --help          # Full help
```

## Development

```bash
git clone https://github.com/ringo380/ga-mcp-full.git
cd ga-mcp-full
python -m venv .venv && source .venv/bin/activate
pip install -e .
ga-mcp-full auth status
```

Project layout:

```
ga_mcp/
├── server.py          # MCP server entrypoint
├── cli.py             # CLI dispatcher
├── auth.py            # OAuth + credential resolution
└── tools/
    ├── admin/         # 11 modules — property, custom dimensions/metrics, audiences, etc.
    ├── reporting/     # 3 modules — core, realtime, metadata
    └── utils.py
```

Public Claude Code artifacts: `.claude-plugin/plugin.json`, `.mcp.json`, `commands/`, `hooks/`.

Issues and PRs welcome at https://github.com/ringo380/ga-mcp-full/issues.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| "Google hasn't verified this app" on the consent screen | Expected during brand verification. Click **Advanced** → **Go to ga-mcp-full**. Or set up your own OAuth client (see README "Power users") |
| `GA auth required: run /ga-mcp-full:auth-login in Claude Code, then retry.` | The cached refresh token is missing or revoked. Rerun the slash command — it's the entire fix |
| OAuth browser window shows "access_denied" during login | Your Google account doesn't have Editor/Admin on any GA4 property. Grant access in **GA4 → Admin → Account/Property Access Management** |
| Token refresh failed | `ga-mcp-full auth logout && ga-mcp-full auth login` |
| `/mcp` shows the server but no tools | Confirm `ga-mcp-full auth status` reports authenticated; tools are gated behind a working Analytics API client |
| Claude Code doesn't see the plugin | `claude plugin list` — confirm `ga-mcp-full@robworks-claude-code-plugins` is installed and enabled. Restart the session if you just enabled it |
| "insufficientPermissions" errors on Admin API writes | Verify your Google account has Editor/Admin role on the target GA4 property |

## Related

- [Robworks Claude Code Plugins marketplace](https://github.com/ringo380/robworks-claude-code-plugins) — catalogs this plugin alongside future plugins from `@ringo380`
- [Claude Code plugin docs](https://code.claude.com/docs/en/plugins)
- [MCP specification](https://modelcontextprotocol.io/)
- [Google Analytics Admin API](https://developers.google.com/analytics/devguides/config/admin/v1)
- [Google Analytics Data API](https://developers.google.com/analytics/devguides/reporting/data/v1)

## License

MIT — see [LICENSE](./LICENSE).
