# Google Search Console MCP Server — Search Analytics, URL Indexing & Sitemap Management for AI Assistants (SEO / LLMO)

`mcp-server-gsc` is an MCP (Model Context Protocol) server for **Google Search Console** that connects your search performance data to Claude or any MCP client. It lets AI assistants query search analytics (clicks, impressions, CTR, position), inspect URL indexing and crawl status, and manage sitemaps — so you can analyze and optimize your website's SEO and LLMO directly from a conversation.

## Tools

| Tool | What It Does | What You Need to Provide |
|---|---|---|
| `get_capabilities` | Lists all tools and shows auth status — call this first if unsure | Nothing |
| `list_properties` | Shows all your GSC properties | Nothing |
| `get_site_details` | Details about a specific site | Site URL |
| `get_search_analytics` | Top queries and pages with clicks, impressions, CTR, position | Site URL, time period |
| `get_performance_overview` | Summary of site performance (totals, daily trend, top 5) | Site URL, time period |
| `compare_search_periods` | Compare performance between two time periods | Site URL, two date ranges |
| `get_search_by_page_query` | Search terms driving traffic to a specific page | Site URL, page URL |
| `get_advanced_search_analytics` | Analytics with filters by country, device, query, page | Site URL |
| `inspect_url_enhanced` | Detailed crawl/index status for a URL | Site URL, page URL |
| `batch_url_inspection` | Inspect up to 10 URLs at once | Site URL, list of URLs |
| `check_indexing_issues` | Check multiple URLs (up to 20) for indexing problems | Site URL, list of URLs |
| `get_sitemaps` | Lists all sitemaps for a site | Site URL |
| `list_sitemaps_enhanced` | Detailed sitemap info including errors and warnings | Site URL |
| `manage_sitemaps` | Submit, delete, or get status of a sitemap | Site URL, action |
| `reauthenticate` | Re-run the OAuth browser login (switch accounts) | Nothing |

## Setup

### 1. Build

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

### 2. Google Cloud credentials

You need a Google Cloud project with the **Search Console API** enabled
([console.cloud.google.com](https://console.cloud.google.com) → APIs & Services → Library → "Google Search Console API" → Enable).

Then pick **one** of the two auth methods:

#### Option A — OAuth (recommended: sign in with your own Google account)

1. APIs & Services → **Credentials** → Create Credentials → **OAuth client ID** → Application type **Desktop app**.
2. If prompted, configure the OAuth consent screen first (External is fine; add your own Google account as a test user).
3. Download the client JSON, or copy the client ID and secret.

Configure via environment variables — either:

```
GSC_OAUTH_CLIENT_ID=xxxx.apps.googleusercontent.com
GSC_OAUTH_CLIENT_SECRET=GOCSPX-...
```

or point to the downloaded JSON:

```
GSC_OAUTH_CREDENTIALS=/path/to/client_secret_xxxx.json
```

On the first tool call (or via the `reauthenticate` tool) a browser window opens for Google sign-in. Tokens are stored in `~/.config/mcp-server-gsc/tokens.json` and refreshed automatically.

#### Option B — Service account (headless, no browser)

1. APIs & Services → Credentials → Create Credentials → **Service account**, then create a JSON key.
2. In Search Console → Settings → Users and permissions, **add the service account email** as a user on each property.

```
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

If `GOOGLE_APPLICATION_CREDENTIALS` is set, it takes precedence and no browser login is used.

### 3. Register with your MCP client

**Claude Code:**

```bash
claude mcp add gsc \
  -e GSC_OAUTH_CLIENT_ID=xxxx.apps.googleusercontent.com \
  -e GSC_OAUTH_CLIENT_SECRET=GOCSPX-... \
  -- node /path/to/mcp-server-gsc/dist/index.js
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/path/to/mcp-server-gsc/dist/index.js"],
      "env": {
        "GSC_OAUTH_CLIENT_ID": "xxxx.apps.googleusercontent.com",
        "GSC_OAUTH_CLIENT_SECRET": "GOCSPX-..."
      }
    }
  }
}
```

## Recommended companion tools for SEO / LLMO

This server is best used for SEO / LLMO in combination with:

- **[KeywordGraph MCP server](https://keywordgraph.com/mcp/)** — lets you compare your Search Console data against real-time search intent data, perform topical cluster analysis, and build knowledge graphs of your queries and content. Connect directly via `https://mcp.keywordgraph.com`, e.g.:

  ```bash
  claude mcp add --transport http keywordgraph https://mcp.keywordgraph.com
  ```
- **[SEO skill](https://keywordgraph.com/seo-skill/)** — adds advanced SEO / LLMO analysis workflows on top of both servers.

Together they enable the full loop: pull your actual performance data from this server, contrast it with what people are searching for right now, find the topical gaps, and optimize your content accordingly — for best results use all three together.

## Usage notes

- **Site URL format matters**: domain properties are `sc-domain:example.com`; URL-prefix properties are `https://example.com/` (exactly as shown in Search Console). Use `list_properties` to see yours.
- **Data lag**: Search Console analytics data lags by roughly 2 days. When you use the `days` shortcut instead of explicit dates, the window automatically ends 2 days ago.
- **Time periods**: analytics tools accept either explicit `startDate`/`endDate` (YYYY-MM-DD) or a trailing `days` count (default 28).
- **Switching accounts**: call the `reauthenticate` tool — it discards stored tokens and reopens the browser login.
- Token storage location can be overridden with `GSC_CONFIG_DIR`.

## Development

```bash
npm run watch   # recompile on change
```

Source layout:

- `src/index.ts` — MCP server and tool definitions
- `src/auth.ts` — OAuth loopback flow, token persistence, service-account support
- `src/gsc.ts` — Search Console API helpers (queries, totals, URL-inspection diagnosis)