# ga-gsc-analytics

Read-only MCP server exposing Google Analytics 4 and Google Search Console data
(`analytics.readonly` + `webmasters.readonly` scopes) to Claude Code / Codex.

**New here?** Follow [`ONBOARDING.md`](ONBOARDING.md) for a zero-to-working walkthrough
(install Claude Code, get credentials, authorize, verify). The rest of this file is
reference material.

> **AI agents**: this file doubles as `AGENTS.md` — start here for setup, then read
> [`skills/analyze-ga-gsc/SKILL.md`](skills/analyze-ga-gsc/SKILL.md) for how to use
> the tools (access checks, default date ranges, GA4 vs. GSC semantics, presentation
> handoff format). Never ask a user to paste credentials into chat.

## Tools

- `analytics_auth_start` / `analytics_auth_status` — local OAuth flow + status check
- `analytics_list_sources` — list GA4 properties and GSC sites available to the authorized account
- `ga_run_report` — run a GA4 report
- `gsc_query_search_analytics` — query Search Console data
- `analytics_presentation_snapshot` — combined GA4 + GSC snapshot for reporting

## Setup (per user)

Each user authorizes with their **own** Google account and keeps their own local
token — never share `client_secret.json` secrets or `tokens.json` between machines.

1. **Google Cloud OAuth client**: create (or reuse an existing) OAuth 2.0 Desktop
   client in Google Cloud Console and download its `client_secret.json`. If the
   consent screen is in "Testing" publishing status, add each new user's Google
   account as a test user first, or auth will fail with access-denied.
2. **Place the credentials** at `~/.config/ga-gsc-analytics/client_secret.json`
   (or point `GA_GSC_CLIENT_SECRET` at a custom path).
3. **Grant data access**: the authorizing Google account needs real permissions on
   the target GA4 property (Analytics Admin → Property Access Management) and the
   GSC site (Search Console → Settings → Users and permissions).
4. **Build the server** (only needed if you change `mcp/server.mjs`; the repo ships
   a prebuilt `mcp/server.bundle.cjs`):
   ```bash
   pnpm install
   pnpm run build   # bundles mcp/server.mjs -> mcp/server.bundle.cjs
   ```
5. **Register the MCP server**. Either:
   - Claude Code, user-level: `claude mcp add ga-gsc-analytics -- node /path/to/ga-gsc-analytics/mcp/server.bundle.cjs`
   - Claude Code / Codex, project-scoped: this repo already ships a relative
     `.mcp.json` (`{"mcpServers": {"ga_gsc_analytics": {"command": "node", "args": ["./mcp/server.bundle.cjs"]}}}`)
     — copy it into a project, or symlink/vendor this whole folder in, and it's
     picked up automatically when that project is opened.
6. **Authorize**: call the `analytics_auth_start` tool from within your AI tool —
   it opens a local browser OAuth flow and writes `~/.config/ga-gsc-analytics/tokens.json`.
7. **Verify**: call `analytics_auth_status` (should report `authorized: true`), then
   `analytics_list_sources` to confirm the expected GA4 properties / GSC sites show up.

## Config overrides

| Env var | Default |
|---|---|
| `GA_GSC_CONFIG_DIR` | `~/.config/ga-gsc-analytics` |
| `GA_GSC_CLIENT_SECRET` | `$GA_GSC_CONFIG_DIR/client_secret.json` |
| `GA_GSC_TOKEN_PATH` | `$GA_GSC_CONFIG_DIR/tokens.json` |

## Development

```bash
pnpm run check   # syntax check
pnpm test        # node --test tests/*.test.mjs
```