# Google Search Console MCP

A production-oriented, read-only Google Search Console MCP server and TypeScript SDK for Claude, Cursor, VS Code, and other MCP clients. Query real Search Console data, inspect indexed URLs, review sitemaps, compare periods, and surface transparent SEO opportunities without handing private data to a third-party SaaS.

The package is currently named `gsc-mcp-ready`; npm availability was checked during development. This repository is not yet claiming public publication, adoption, or eligibility metrics.

```bash
npx -y gsc-mcp-ready auth
```

Then paste:

```json
{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "gsc-mcp-ready"]
    }
  }
}
```

> `gsc-mcp-ready` is the starter package name. Replace it with your final npm package name before publishing.

## Authentication choices

### Browser login — best end-user DX

When the npm publisher bundles a verified Google Desktop OAuth client into the release:

```bash
npx -y gsc-mcp-ready auth
```

The browser opens, the user approves read-only Search Console access, and the package securely stores a refresh token in the OS configuration directory.

A source clone without bundled OAuth values uses:

```bash
npm install
npm run build
node dist/cli.js auth --client /absolute/path/oauth-client.json
```

### Service-account JSON — best for servers and CI

```json
{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "gsc-mcp-ready"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/absolute/path/service-account.json"
      }
    }
  }
}
```

The service-account email must be added to the Search Console property.

## Tools

| Tool | Purpose |
|---|---|
| `gsc_list_sites` | List accessible Search Console properties |
| `gsc_get_site` | Get one property’s permission level |
| `gsc_search_analytics` | Query clicks, impressions, CTR, and position |
| `gsc_query_*` | Convenience queries grouped by page, query, country, device, or appearance |
| `gsc_top_pages` / `gsc_top_queries` | Compact top-performance views |
| `gsc_compare_periods` | Compare equal or explicit date ranges |
| `gsc_find_opportunities` | Find high-impression, low-CTR queries/pages |
| `gsc_inspect_url` | Inspect Google's indexed version of a URL |
| `gsc_bulk_inspect_urls` | Bounded-concurrency URL inspection with partial failures |
| `gsc_list_sitemaps` | List submitted sitemaps |
| `gsc_get_sitemap` | Get one sitemap’s status |
| `gsc_server_info` | Show local server metadata and safety settings |

Search Analytics supports dimensions `query`, `page`, `country`, `device`, `date`, `hour`, and `searchAppearance`; filters; result types; aggregation; finalized or fresh data; and safe pagination. Google documents that Search Analytics returns top rows and does not guarantee every underlying row; the result explicitly reports this limitation.

## Clone workflow

```bash
git clone https://github.com/your-org/gsc-mcp.git
cd gsc-mcp
npm install
npm run check
```

MCP configuration for a clone:

```json
{
  "mcpServers": {
    "google-search-console-local": {
      "command": "node",
      "args": ["/absolute/path/gsc-mcp/dist/cli.js"]
    }
  }
}
```

## CLI

```text
gsc-mcp auth [--client oauth-client.json] [--no-open]
gsc-mcp serve [--transport stdio|http]
gsc-mcp doctor [--credentials service-account.json]
gsc-mcp sites [--credentials service-account.json]
gsc-mcp config [--credentials /absolute/path/service-account.json]
gsc-mcp logout
```

Generate a config snippet:

```bash
gsc-mcp config
gsc-mcp config --credentials /absolute/path/service-account.json
```

## TypeScript library

```typescript
import { GscClient, resolveGoogleAuth } from 'gsc-mcp-ready';

const resolved = await resolveGoogleAuth({
  credentialsPath: '/absolute/path/service-account.json'
});

const gsc = new GscClient({ auth: resolved.auth });
const sites = await gsc.listSites();
const analytics = await gsc.searchAnalytics({
  siteUrl: 'sc-domain:example.com',
  startDate: '2026-07-01',
  endDate: '2026-07-31',
  dimensions: ['query'],
  maxRows: 1000
});

console.log({ sites, analytics });
```

## HTTP/cloud mode

```bash
GSC_CREDENTIALS_PATH=/run/secrets/gsc.json \
GSC_HTTP_AUTH_TOKEN='replace-with-a-long-random-secret' \
gsc-mcp serve --transport http --host 0.0.0.0 --port 3000
```

HTTP endpoint: `http://host:3000/mcp`. Health check: `/healthz`. Non-loopback HTTP binding is refused without a bearer token.

## Production safeguards

- Read-only Google OAuth scope
- OS-specific token storage with POSIX mode `0600`
- No stdout logging in stdio mode
- Retry with exponential backoff for rate limits and transient server failures
- Request timeout controls
- Strict argument validation
- URL-to-property validation before URL Inspection calls
- Bearer protection for remote HTTP
- Credential redaction in logs and errors
- Dependency updates and Node 20/22 CI

## Configuration

| Variable | Meaning |
|---|---|
| `GSC_CREDENTIALS_PATH` | Service-account JSON path |
| `GOOGLE_APPLICATION_CREDENTIALS` | Standard Google credential path fallback |
| `GSC_CREDENTIALS_JSON` | Raw/base64 service-account JSON for secret injection |
| `GSC_TOKEN_PATH` | Override saved OAuth token location |
| `GSC_CONFIG_DIR` | Override application configuration directory |
| `GSC_USE_ADC` | Enable Application Default Credentials fallback |
| `GSC_MCP_TRANSPORT` | `stdio` or `http` |
| `GSC_MCP_HOST` / `GSC_MCP_PORT` | HTTP bind settings |
| `GSC_HTTP_AUTH_TOKEN` | Required bearer token for non-loopback HTTP |
| `GSC_REQUEST_TIMEOUT_MS` | Google API timeout, default 30000 |
| `GSC_MAX_RETRIES` | Transient retry count, default 3 |
| `GSC_LOG_LEVEL` | `debug`, `info`, `warn`, `error`, or `silent` |
| `GSC_TEXT_PREVIEW_ROWS` | Rows included in model-facing text, default 50 |
| `GSC_EXPOSE_ERROR_DETAILS` | Set `1` only for controlled debugging |

## Documentation

- [60-second getting started guide](docs/getting-started.md)
- [Client configuration notes](docs/client-configs.md)
- [Ecosystem analysis and positioning](docs/research/ecosystem-analysis.md)
- [Architecture and flow](docs/ARCHITECTURE.md)
- [Authentication](docs/AUTHENTICATION.md)
- [Deployment](docs/DEPLOYMENT.md)
- [Development and release](docs/DEVELOPMENT.md)
- [Security](SECURITY.md)
- [Roadmap](ROADMAP.md)
- [Contributing](CONTRIBUTING.md)

## License

MIT