# searchconsole-mcp

MCP server that automates Google Search Console for your projects: search analytics, sitemap management, site properties and URL inspection.

## Tools

| Tool | Description |
| --- | --- |
| `gsc_list_sites` | List all properties the service account can access |
| `gsc_add_site` / `gsc_remove_site` | Add/remove a property (`sc-domain:example.com` or `https://www.example.com/`) |
| `gsc_search_analytics` | Clicks, impressions, CTR, position grouped by query/page/country/device/date, with filters. Defaults to last 28 days |
| `gsc_list_sitemaps` / `gsc_get_sitemap` | Inspect submitted sitemaps and indexed counts |
| `gsc_submit_sitemap` / `gsc_delete_sitemap` | Submit or remove sitemaps |
| `gsc_inspect_url` | URL Inspection API: index status, canonical, crawl info, mobile usability |

## One-time Google setup

1. In [Google Cloud Console](https://console.cloud.google.com/) create a project.
2. Enable the **Google Search Console API** (APIs & Services > Library).
3. Create a **Service account** (IAM & Admin > Service Accounts) and download a **JSON key**.
4. For each Search Console property: **Settings > Users and permissions > Add user**, paste the service account email (`...@...iam.gserviceaccount.com`) and grant **Owner** (Owner is required for the URL Inspection API).

## Configuration

Environment variables:

| Var | Required | Description |
| --- | --- | --- |
| `GSC_SERVICE_ACCOUNT_JSON` | one of | Full service-account JSON key inline |
| `GSC_SERVICE_ACCOUNT_FILE` | one of | Path to the key file. Defaults to `./service-account.json` |
| `GSC_DEFAULT_SITE` | optional | Default property so you can omit `siteUrl` per call |

The server also loads `.env` from its working directory at startup.

## Register in an MCP client

opencode (`~/.config/opencode/opencode.json` or project `.opencode/opencode.json`):

```json
{
  "mcp": {
    "searchconsole": {
      "type": "local",
      "command": ["node", "/absolute/path/to/searchconsole-mcp/dist/index.js"],
      "environment": {
        "GSC_SERVICE_ACCOUNT_FILE": "/absolute/path/to/service-account.json",
        "GSC_DEFAULT_SITE": "sc-domain:example.com"
      }
    }
  }
}
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "searchconsole": {
      "command": "node",
      "args": ["/absolute/path/to/searchconsole-mcp/dist/index.js"],
      "env": {
        "GSC_SERVICE_ACCOUNT_FILE": "/absolute/path/to/service-account.json",
        "GSC_DEFAULT_SITE": "sc-domain:example.com"
      }
    }
  }
}
```

## Development

```sh
npm install
npm run build     # tsc -> dist/
npm start         # run the server on stdio
npm run smoke     # boots the server and lists tools
```

## Notes

- Analytics data lags ~2 days; pass `dataState: "all"` to include fresh partial data.
- The API caps analytics rows at 25,000 per request; use `startRow` to page.
- Adding a site via API leaves it unverified until ownership is confirmed; easiest path is adding the service account email as an Owner in the UI first.