# MCP Site Analyst

An MCP (Model Context Protocol) server that provides Google Analytics (GA4) and Google Search Console data as tools for AI assistants.

## Features

- **13 tools** across two Google services
  - **Google Analytics (GA4)**: Custom reports, realtime data, metadata discovery, top pages, traffic sources, demographics
  - **Google Search Console**: Search analytics, sitemaps, URL inspection, site listing, top queries, top pages
- **Dual transport**: stdio (local) and stateless HTTP (remote)
- **Flexible auth**: Service account key file, inline JSON credentials, Application Default Credentials, or CLI argument
- **Configurable GA4 Property ID**: Set once at server level or per-tool call
- **Optional Bearer token auth** for HTTP mode

## Prerequisites

1. **Google Cloud Project** with these APIs enabled:
   - [Google Analytics Data API](https://console.cloud.google.com/apis/library/analyticsdata.googleapis.com)
   - [Google Search Console API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com)

2. **Service Account** with a downloaded JSON key file:
   - Go to [IAM & Admin > Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)
   - Create a service account → Keys → Add Key → JSON

3. **Grant access** to the service account:
   - **GA4**: Admin > Property Access Management > Add the service account email as Viewer
   - **Search Console**: Settings > Users and permissions > Add the service account email

## Installation

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

## Usage

### stdio mode (Claude Desktop, Gemini CLI, etc.)

```bash
# Using CLI argument
node build/index.js --key-file /path/to/key.json

# Using environment variable
GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json node build/index.js

# With a default GA4 Property ID
node build/index.js --key-file /path/to/key.json --property-id 123456789
```

### HTTP mode

```bash
# Default port 3000
node build/index.js --http --key-file /path/to/key.json

# Custom port
node build/index.js --http --port 8080 --key-file /path/to/key.json

# With Bearer token authentication
MCP_AUTH_TOKEN=my-secret-token node build/index.js --http --key-file /path/to/key.json
```

The HTTP endpoint is available at `POST http://localhost:3000/mcp` (Streamable HTTP, stateless).
A health check endpoint is available at `GET http://localhost:3000/health`.

### Authentication

The server resolves Google credentials in this order:

| Priority | Method | Description |
|----------|--------|-------------|
| 1 | `--key-file <path>` | CLI argument pointing to a service account JSON key file |
| 2 | `GOOGLE_CREDENTIALS_JSON` | Environment variable containing the full JSON key as a string (useful for containers/CI) |
| 3 | `GOOGLE_APPLICATION_CREDENTIALS` | Environment variable pointing to a key file path |
| 4 | Application Default Credentials | Automatic on Cloud Run, GCE, or when authenticated via `gcloud auth application-default login` |

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "site-analyst": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-site-analyst/build/index.js",
        "--key-file",
        "/absolute/path/to/key.json",
        "--property-id",
        "YOUR_GA4_PROPERTY_ID"
      ]
    }
  }
}
```

### Gemini CLI Configuration

Add to your `.gemini/settings.json`:

```json
{
  "mcpServers": {
    "site-analyst": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-site-analyst/build/index.js",
        "--key-file",
        "/absolute/path/to/key.json"
      ]
    }
  }
}
```

### Remote HTTP Configuration

If deployed to a remote server (e.g. Cloud Run), configure your client to use the HTTP endpoint:

```json
{
  "mcpServers": {
    "site-analyst": {
      "httpUrl": "https://your-service-url/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
      }
    }
  }
}
```

## Deploying to Cloud Run

A deployment script is included for Google Cloud Run.

### Setup

```bash
# Copy the example env file and fill in your values
cp .env.example .env

# Edit .env with your GCP project ID, region, and GA4 property ID
```

See `.env.example` for all available configuration options.

### Deploy

```bash
# Deploy with Cloud Build (no local Docker required)
./deploy.sh --cloud-build

# Deploy with local Docker build
./deploy.sh

# Deploy with Bearer token auth enabled
./deploy.sh --token "my-secret-token"
```

On Cloud Run the server uses Application Default Credentials automatically via the configured service account — no key file is needed.

## Tools Reference

### Google Analytics (GA4)

| Tool | Description |
|------|-------------|
| `ga4_run_report` | Run a custom report with flexible dimensions, metrics, date ranges, filters, and sorting |
| `ga4_realtime_report` | Get real-time active user data (last 30 minutes) |
| `ga4_get_metadata` | Discover all available dimensions and metrics |
| `ga4_top_pages` | Shortcut: Top pages by pageviews |
| `ga4_top_traffic_sources` | Shortcut: Top traffic sources by sessions |
| `ga4_user_demographics` | Shortcut: User breakdown by country/city/language |

### Google Search Console

| Tool | Description |
|------|-------------|
| `gsc_search_analytics` | Query search performance (clicks, impressions, CTR, position) with filters |
| `gsc_list_sitemaps` | List all submitted sitemaps |
| `gsc_get_sitemap` | Get details for a specific sitemap |
| `gsc_inspect_url` | Inspect a URL's index status and mobile usability |
| `gsc_list_sites` | List all sites accessible by the service account |
| `gsc_top_queries` | Shortcut: Top search queries by clicks |
| `gsc_top_pages` | Shortcut: Top pages by clicks in search |

## Development

```bash
# Run in dev mode (no build step needed)
npx tsx src/index.ts --key-file /path/to/key.json

# Build
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js --key-file /path/to/key.json
```

## License

MIT