# search-console-mcp

Superfast, stdio-first MCP server for Google Search Console with:

- Fast startup
- Typed tool inputs
- In-memory TTL caching + request coalescing
- OAuth 2.0 refresh-token authentication

## Features

Available MCP tools:

1. `list_sites`
2. `query_performance`
3. `inspect_url`
4. `list_sitemaps`
5. `get_sitemap`

## Requirements

- Node.js 20+
- pnpm 9+
- Google Search Console property access
- OAuth client credentials + refresh token

## Quick Start (Plug & Play)

1. **Get your refresh token** (one-time setup):
```bash
pnpm install
pnpm auth
```
This will:
- Prompt for your Client ID and Secret
- Open your browser for authorization
- Save credentials to `.env` automatically

2. **Build and run**:
```bash
pnpm build
pnpm start
```

That's it! The server reads credentials from `.env` automatically.

## Getting Credentials

### Step 1: Create OAuth Client ID on Google Cloud Console

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project (or use an existing one)
3. Enable the **Google Search Console API**:
   - Navigate to "APIs & Services" → "Library"
   - Search for "Google Search Console API"
   - Click "Enable"
4. Create OAuth 2.0 credentials:
   - Go to "APIs & Services" → "Credentials"
   - Click "Create Credentials" → "OAuth client ID"
   - Choose "Desktop application" or "Web application"
   - Add redirect URI: `http://localhost:9876` (unique port to avoid conflicts)
   - Copy the **Client ID** and **Client Secret**

### Step 2: Get Refresh Token

**Easiest way** — use the built-in script:

```bash
pnpm install
pnpm auth
```

This will:
1. Prompt for Client ID and Secret
2. Open your browser for authorization
3. Automatically save to `.env`

**Manual alternative** if needed — use Google's [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/):
1. Configure the OAuth Client ID (gear icon)
2. Use scope: `https://www.googleapis.com/auth/webmasters`
3. Authorize and copy the refresh token

### Step 3: Find Your Search Console Site URL

1. Go to [Google Search Console](https://search.google.com/search-console/)
2. Select your property
3. In the URL bar, you'll see a property like:
   - `sc-domain:example.com` (domain property)
   - `https://example.com` (URL prefix property)
4. Copy this value as your `GSC_SITE_URL`

## Setup

After `pnpm auth` creates your `.env`, you're ready to go:

```bash
pnpm build
pnpm start
```

The server automatically reads `GSC_CLIENT_ID`, `GSC_CLIENT_SECRET`, `GSC_REFRESH_TOKEN`, and `GSC_SITE_URL` from `.env`.

### Manual .env Setup (optional)

If you prefer to create `.env` manually:

```bash
cat > .env << 'EOF'
GSC_CLIENT_ID="your-client-id"
GSC_CLIENT_SECRET="your-client-secret"
GSC_REFRESH_TOKEN="your-refresh-token"
GSC_SITE_URL="sc-domain:example.com"
GSC_CACHE_TTL_MS="30000"
GSC_HTTP_TIMEOUT_MS="12000"
GSC_HTTP_RETRIES="2"
EOF
```

Then run:

```bash
pnpm build
pnpm start
```

## Docker

Build image:

```bash
docker build -t search-console-mcp .
```

Run with `.env` file (easiest):

```bash
docker run --rm -i --env-file .env search-console-mcp
```

Or pass env vars directly:

```bash
docker run --rm -i \
	-e GSC_CLIENT_ID="your-client-id" \
	-e GSC_CLIENT_SECRET="your-client-secret" \
	-e GSC_REFRESH_TOKEN="your-refresh-token" \
	-e GSC_SITE_URL="sc-domain:example.com" \
	search-console-mcp
```

## AI Agent Integration

### Claude Desktop

#### Option 1: Docker via local MCP config (Recommended)

This is the most reliable Claude Desktop setup: no custom connector UI, no remote URL, no TLS hassle.

1. Build image:
```bash
docker build -t search-console-mcp .
```

2. Add this to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
	"mcpServers": {
		"search-console": {
			"command": "docker",
			"args": [
				"run",
				"--rm",
				"-i",
				"--env-file",
				"/absolute/path/search-console-mcp/.env",
				"search-console-mcp"
			]
		}
	}
}
```

Example absolute path:
```text
/Users/devbyray/Projects/devbyrayray/search-console-mcp/.env
```

3. Restart Claude Desktop.

#### Option 2: Local Node.js process (stdio)

```json
{
	"mcpServers": {
		"search-console": {
			"command": "bash",
			"args": ["-c", "cd /absolute/path/search-console-mcp && source .env && pnpm start"]
		}
	}
}
```

#### Option 3: Custom Connector UI (remote MCP URL)

Use this only when you have a real remote endpoint.

- URL must be `https://.../mcp`
- Certificate must be trusted by Claude (public CA certificate)
- `localhost` + self-signed certificates may fail in Custom Connector mode

For local development, prefer Option 1 or 2.

### Claude Code (VS Code Extension)

Create `.env.local` in your project, then add to VS Code settings:

```json
{
	"claude.mcpServers": {
		"search-console": {
			"command": "bash",
			"args": ["-c", "cd /absolute/path/search-console-mcp && source .env && node dist/index.js"]
		}
	}
}
```

### GitHub Copilot

Best approach: Use `.env` with the server:

```bash
source .env && pnpm start
```

Then configure Copilot CLI to connect to the running server.

### Docker Integration for AI Agents

For containerized deployments, use `.env`:

```bash
docker build -t search-console-mcp .
docker run --rm -i --env-file .env search-console-mcp
```

### Other MCP Clients

All MCP clients can read `.env` files. Example configuration structure:

```json
{
	"command": "bash",
	"args": ["-c", "cd /path/to/search-console-mcp && source .env && node dist/index.js"]
}
```

Or pass env vars directly from your `.env` file to the client configuration.

## MCP Client Configuration Example

Generic reference (use `.env` for actual values):

```json
{
	"mcpServers": {
		"search-console": {
			"command": "node",
			"args": ["/absolute/path/search-console-mcp/dist/index.js"],
			"env": {
				"GSC_CLIENT_ID": "your-client-id",
				"GSC_CLIENT_SECRET": "your-client-secret",
				"GSC_REFRESH_TOKEN": "your-refresh-token",
				"GSC_SITE_URL": "sc-domain:example.com"
			}
		}
	}
}
```

## OAuth Refresh Token Notes

Use any OAuth 2.0 flow that produces a Google refresh token for the same client ID/secret pair. The server only needs the refresh token and will rotate access tokens automatically.

## Development

```bash
pnpm dev
```

Tests:

```bash
pnpm test
```

Lint:

```bash
pnpm lint
```

## Troubleshooting

- `Missing required environment variable`: check all required `GSC_*` vars.
- `token_refresh_failed`: verify OAuth client ID/secret and refresh token pair.
- `google_api_error` with `403`: verify account access to the requested property.
- `429`/`5xx`: retries are automatic; reduce request volume or increase interval between calls.