# SEO Analytics MCP

MCP server for Google Search Console (GSC) + Google Analytics 4 (GA4).

## How It Works

### What `.venv` Means

- `.venv` is this project's private Python environment.
- It contains its own Python interpreter and dependencies for this repo only.
- `run-local.sh` activates `.venv` so the MCP server runs with the correct package versions.

### What `stdio` Means

- `stdio` means the MCP client and server communicate through standard input/output streams.
- The client starts `run-local.sh`, sends tool requests in, and reads JSON responses out.
- No web server or HTTP endpoint is required for the default local setup.

1. Your MCP client (Claude/Codex) launches `run-local.sh` as a stdio server process.
2. `run-local.sh` prepares `.venv`, installs dependencies, loads `config/.env`, and validates `config/service-account.json`.
3. The Python server (`seo-analytics-mcp`) receives tool calls, fetches data from GSC/GA4 using the service account, and computes merged analysis outputs.
4. Results are returned to the MCP client as structured JSON.

## Deployment Model

- This project is deployed as a local process on your machine via stdio.
- It is not an HTTP API service by default and does not require cloud hosting.
- To "deploy" it for another environment, clone the repo there, provide `config/.env` and `config/service-account.json`, then register that machine's `run-local.sh` path in the MCP client.

## Prerequisites

- Python 3.11+

## Quick Start

1. Create local config files from templates:

```bash
cp config/.env.example config/.env
cp config/service-account.example.json config/service-account.json
```

2. Fill required values:
- `config/.env`
  - `DEFAULT_GSC_SITE_URL` (required format: `sc-domain:example.com`)
  - `DEFAULT_GA4_PROPERTY_ID`
- `config/service-account.json`
  - Replace all `REPLACE_WITH_...` fields with real Google service-account values.

3. Run the server:

```bash
./run-local.sh
```

The script creates/uses `.venv`, installs dependencies, loads `config/.env`, validates credentials, and starts `seo-analytics-mcp` over stdio.

## MCP Client Setup

Use the local launcher script as the MCP server command:

```text
/absolute/path/to/analytics/run-local.sh
```

### Codex App

Add server:

```bash
codex mcp add seo-analytics -- /absolute/path/to/analytics/run-local.sh
```

Verify:

```bash
codex mcp list
```

Remove:

```bash
codex mcp remove seo-analytics
```

### Claude Code CLI

Add server:

```bash
claude mcp add -s project seo-analytics -- /absolute/path/to/analytics/run-local.sh
```

Verify:

```bash
claude mcp list
```

Remove:

```bash
claude mcp remove seo-analytics
```

### Claude Desktop App (macOS)

1. Quit Claude Desktop completely.
2. Edit `~/Library/Application Support/Claude/claude_desktop_config.json`.
3. Add this server entry (merge into existing `mcpServers` if present):

```json
{
  "mcpServers": {
    "seo-analytics": {
      "type": "stdio",
      "command": "/absolute/path/to/analytics/run-local.sh",
      "args": []
    }
  }
}
```

4. Start Claude Desktop again.
5. In a new chat, run tool `capabilities` to confirm connection.

## Main Tools

- `capabilities`
- `gsc_list_sites`
- `gsc_top_pages`
- `gsc_top_queries`
- `ga4_landing_pages`
- `analytics_merge_page_metrics`
- `analytics_generate_action_items`
- `analytics_trend_report`
- `analytics_data_quality_report`

## Screenshots

These screenshots are example outputs produced by using Claude Code with this MCP server.
The MCP provides the underlying GSC/GA4 data and analytics tools; dashboard rendering is not generated by default by the server itself.
For privacy reasons, values shown in the screenshots are randomized; the actual workflow was executed against real data.

![MCP Dashboard View 1](docs/images/mcp-dashboard-01.png)
![MCP Dashboard View 2](docs/images/mcp-dashboard-02.png)
![MCP Dashboard View 3](docs/images/mcp-dashboard-03.png)

## Troubleshooting

- `service-account.json still contains placeholder values`
  - Replace all `REPLACE_WITH_...` fields in `config/service-account.json`.
- `No such file or directory: .../credentials/service-account.json`
  - You have a stale credential env override from an older setup.
  - Re-add the MCP server so it runs the latest `run-local.sh` and uses `config/service-account.json`.
- `Operation not permitted` when Claude Desktop starts MCP
  - macOS is blocking execution from protected folders (commonly `~/Documents`).
  - Either grant Claude Desktop access in `System Settings -> Privacy & Security` (`Files and Folders` and/or `Full Disk Access`) or move the repo to a non-protected path like `~/dev/analytics`.
  - After changing permissions/path, restart Claude Desktop and re-add the MCP entry if needed.
- `Missing property_id and DEFAULT_GA4_PROPERTY_ID is not set`
  - Set `DEFAULT_GA4_PROPERTY_ID` in `config/.env`.
- `Missing site_url...`
  - Set `DEFAULT_GSC_SITE_URL` in `config/.env`.
- GSC permission error on `https://...` property
  - This server enforces GSC properties in `sc-domain:<domain>` format to avoid URL-prefix mismatch issues.
  - Use a Domain property in Search Console and grant your service account access there.

## Security

- Never commit `config/service-account.json` or `config/.env`.
- Commit only template files:
  - `config/service-account.example.json`
  - `config/.env.example`