# ga4-gsc-clarity-mcp-server

An MCP server that gives Claude read access to **Google Analytics 4 (GA4)**, **Google Search
Console (GSC)**, and **Microsoft Clarity** — set up once, reusable from any project.

## How it's scalable across projects

Connections (a Google account, a Clarity project token) are stored in `~/.analytics-mcp-server/`,
not inside this repo or any single project. You register the server once with `claude mcp add
--scope user`, and every Claude Code project on your machine can then use `list_connections` and
the `ga4_*` / `gsc_*` / `clarity_*` tools against any connection by name — no per-project setup,
no re-authenticating for each new site or repo. Adding a new GA4 property, GSC site, or Clarity
project later is just another `npm run cli -- add-*` call; no code changes needed.

## Important note on auth

Google's GA4 and Search Console APIs support OAuth, and this server uses it. **Microsoft Clarity's
Data Export API does not support OAuth** — Clarity only issues per-project API tokens from its
dashboard (Settings → Data Export), capped at 10 requests/day/token. Clarity connections in this
server use that token, stored the same way as Google's refresh tokens. This is a limitation of
Clarity's API, not a design choice here.

## Setup

### 1. Install

```bash
npm install
npm run build
```

### 2. Create a Google OAuth client (for GA4 + Search Console)

1. In [Google Cloud Console](https://console.cloud.google.com/apis/credentials), create/select a project.
2. Enable these APIs: **Google Analytics Admin API**, **Google Analytics Data API**, **Search Console API**.
3. Create an OAuth client with type **Desktop app**.
4. Copy `.env.example` to `.env` and fill in `GOOGLE_OAUTH_CLIENT_ID` / `GOOGLE_OAUTH_CLIENT_SECRET`.

### 3. Add connections

Each connection is added once via the CLI, which handles secrets outside of any LLM conversation.

```bash
# Opens a browser for Google consent, stores a refresh token under the given name.
npm run cli -- add-google my-google         # both GA4 + GSC scopes
npm run cli -- add-google my-google --ga4   # GA4 only
npm run cli -- add-google my-google --gsc   # GSC only

# Stores a Clarity project token (generate one at https://clarity.microsoft.com,
# Settings > Data Export).
npm run cli -- add-clarity my-site --token <token> --label "My Site"

npm run cli -- list
npm run cli -- remove <name>
```

You can add as many named connections as you like — multiple Google accounts, multiple Clarity
projects — and refer to any of them from any project by name.

### 4. Register the MCP server with Claude Code

```bash
claude mcp add --scope user analytics-mcp-server \
  --env GOOGLE_OAUTH_CLIENT_ID=<your-client-id> \
  --env GOOGLE_OAUTH_CLIENT_SECRET=<your-client-secret> \
  -- node /absolute/path/to/analytics-mcp-server/dist/src/index.js
```

`--scope user` makes it available in every project, which is the point — connections live outside
any repo, so this only needs to be done once per machine.

## Tools

| Tool | Purpose |
|---|---|
| `list_connections` | List configured connections by name |
| `ga4_list_properties` | List GA4 properties visible to a Google connection |
| `ga4_run_report` | Run a historical GA4 report (dimensions/metrics/date range) |
| `ga4_run_realtime_report` | Run a GA4 realtime (~last 30 min) report |
| `gsc_list_sites` | List Search Console properties visible to a Google connection |
| `gsc_query_search_analytics` | Query clicks/impressions/CTR/position by dimension |
| `gsc_inspect_url` | Check a URL's index status |
| `clarity_get_insights` | Fetch Clarity traffic/engagement metrics (1-3 day window, cached hourly) |

## Adding another provider later

Follow the existing pattern to extend this to a new service (e.g. Meta Ads, another analytics tool):

1. `src/providers/<service>.ts` — API client functions, no MCP-specific code.
2. `src/tools/<service>Tools.ts` — `registerTool` calls that wrap the provider functions.
3. Register the new tools in `src/index.ts`.
4. If it needs OAuth, add a `run<Service>InteractiveAuth` in `src/auth/` and an `add-<service>`
   command in `scripts/cli.ts`, following `googleOAuth.ts`. If it only needs an API key/token,
   just add it to `ConnectionStore`'s `Connection` union and a CLI command, like Clarity.

## Development

```bash
npm run dev     # run the server with auto-reload (tsx)
npm run build   # type-check + compile to dist/
```