Google Search Console MCP

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.

npx -y gsc-mcp-ready auth

Then paste:

{
  "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:

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:

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

Service-account JSON — best for servers and CI

{
  "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

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

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

MCP configuration for a clone:

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

CLI

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:

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

TypeScript library

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

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

Documentation

• 60-second getting started guide
• Client configuration notes
• Ecosystem analysis and positioning
• Architecture and flow
• Authentication
• Deployment
• Development and release
• Security
• Roadmap
• Contributing

License

MIT