# Google Search Console MCP

Stdio MCP server for Google Search Console. It focuses on keyword mining, Search Analytics metrics, sitemap management across multiple properties, and URL index inspection.

## Install

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

For a published package, install it globally or use the `gsc-mcp` binary from your package manager. This scoped package is configured for public npm access.

## Auth

For personal use from npm, create a Desktop OAuth client in Google Cloud, enable the Search Console API, download the OAuth client JSON, then run:

```bash
npx @rohoswagger/google-search-console-mcp auth \
  --client-secrets ~/Downloads/client_secret_....json
```

The browser consent flow saves the client ID, client secret, and refresh token to your user config directory. Nothing sensitive is printed to stdout. The default credential locations are:

- macOS: `~/Library/Application Support/google-search-console-mcp/credentials.json`
- Linux: `${XDG_CONFIG_HOME:-~/.config}/google-search-console-mcp/credentials.json`
- Windows: `%APPDATA%/google-search-console-mcp/credentials.json`

The credentials file and its directory use owner-only permissions. Future `npx ...` or globally installed `gsc-mcp` processes load it automatically.

Environment variables remain available as overrides:

```bash
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REFRESH_TOKEN=...
```

For repository development, you can instead copy `.env.example` to `.env` and fill in the client ID and secret before running `npm run dev -- auth`. The callback updates that env file as well as the persistent user credentials file. `.env` is gitignored.

The server also accepts `GOOGLE_ACCESS_TOKEN` for quick tests and `GOOGLE_APPLICATION_CREDENTIALS` for Application Default Credentials. Service accounts only work for Search Console if the service account email has access to the property.

The auth helper uses `http://127.0.0.1:53682/oauth2callback` by default. Add that redirect URI to your OAuth client, or set `GOOGLE_REDIRECT_URI` and `GSC_MCP_AUTH_PORT` to match your Google Cloud configuration.

## MCP config

Example client config:

```json
{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "@rohoswagger/google-search-console-mcp"]
    }
  }
}
```

The example assumes you authenticated once with the `npx ... auth --client-secrets ...` command. No credentials need to be copied into the MCP client configuration.

## Tools

- `gsc_list_sites`: lists all properties available to the authenticated account.
- `gsc_search_analytics`: raw Search Analytics query for one property, selected properties, or all properties.
- `gsc_top_queries`: convenience keyword mining tool for queries/pages across one or many properties.
- `gsc_keyword_opportunities`: finds high-impression, low-CTR queries across one or many properties.
- `gsc_search_appearance_types`: discovers `searchAppearance` values available for a property.
- `gsc_list_sitemaps`: lists submitted sitemaps.
- `gsc_get_sitemap`: fetches sitemap status and metadata.
- `gsc_submit_sitemap`: submits a sitemap. Requires `https://www.googleapis.com/auth/webmasters`.
- `gsc_delete_sitemap`: deletes a submitted sitemap. Requires `https://www.googleapis.com/auth/webmasters`.
- `gsc_batch_submit_sitemaps`: submits sitemap URLs across multiple properties with per-target results.
- `gsc_batch_delete_sitemaps`: deletes sitemap URLs across multiple properties with per-target results.
- `gsc_inspect_url`: checks indexed URL status.

## AI search visibility

Google Search Console has a dedicated Generative AI performance report in the UI, rolled out worldwide on August 31, 2026. The public Search Console API docs do not expose a matching REST endpoint yet. Google documents AI Overviews and AI Mode as included in the `web` search type in Search Console performance data.

The practical API path today is:

1. Use `gsc_search_analytics` or `gsc_top_queries` with `type: "web"` for clicks, impressions, CTR, and position.
2. Use `gsc_search_appearance_types` to discover any `searchAppearance` values Google exposes for your property.
3. Treat dedicated Generative AI report data as UI/export-only until Google adds it to the API.

## Useful examples

Top Gojo alternative-query impressions across all connected sites:

```json
{
  "allSites": true,
  "startDate": "2026-08-01",
  "endDate": "2026-08-31",
  "type": "web",
  "queryContains": "alternatives",
  "limit": 100
}
```

Find queries around a competitor page:

```json
{
  "siteUrl": "sc-domain:example.com",
  "startDate": "2026-08-01",
  "endDate": "2026-08-31",
  "pageContains": "notchnook-alternatives",
  "includePages": true,
  "limit": 500
}
```

Find high-impression queries that are earning few clicks:

```json
{
  "allSites": true,
  "startDate": "2026-08-01",
  "endDate": "2026-08-31",
  "minImpressions": 100,
  "maxCtr": 0.03,
  "includePages": true,
  "limit": 5000
}
```

Submit a sitemap:

```json
{
  "siteUrl": "https://example.com/",
  "feedpath": "https://example.com/sitemap.xml"
}
```

List sitemaps for every connected property:

```json
{
  "allSites": true
}
```

Submit sitemaps across several properties:

```json
{
  "targets": [
    {
      "siteUrl": "sc-domain:example.com",
      "feedpath": "https://example.com/sitemap.xml"
    },
    {
      "siteUrl": "https://docs.example.com/",
      "feedpath": "https://docs.example.com/sitemap.xml"
    }
  ]
}
```

## References

- Search Analytics API: https://developers.google.com/webmaster-tools/v1/searchanalytics/query
- Getting all Search Analytics data: https://developers.google.com/webmaster-tools/v1/how-tos/all-your-data
- Sites API: https://developers.google.com/webmaster-tools/v1/sites/list
- Sitemaps API: https://developers.google.com/webmaster-tools/v1/sitemaps
- URL Inspection API: https://developers.google.com/webmaster-tools/v1/urlInspection.index/inspect
- AI features and Search Console measurement: https://developers.google.com/search/docs/appearance/ai-features
- Generative AI performance report: https://support.google.com/webmasters/answer/16984139
- MCP TypeScript server SDK: https://github.com/modelcontextprotocol/typescript-sdk