mcp-google-search-console 2.0.0

MCP server for Google Search Console with automated SEO audit reports

Google Search Console MCP

MCP (Model Context Protocol) server for Google Search Console. Query Search Console data and generate complete HTML SEO audit reports directly from any MCP-compatible client (Claude Code, Claude Desktop, Cursor, Zed, Continue, ...).

Features

• Read-only access to Search Console (no write operations to your properties)
• 8 tools covering sites, queries, pages, devices, countries, indexing, sitemaps, URL inspection
• gsc_audit: one-call generator for a self-contained HTML report with Chart.js graphs, automatic issue detection, concrete examples, actionable strategy and a 30/60/90-day roadmap
• Brandable reports: customize logo, font, colors via branding.json
• Stateless-friendly: credentials via environment variables, or XDG config dir

Tools

Tool	Description
gsc_sites	List all verified sites
gsc_site_details	Details of a specific site
gsc_query	Performance report with dimensions (query, page, country, device, date)
gsc_performance_overview	Aggregated metrics for a period (clicks, impressions, CTR, position)
gsc_indexing_issues	Check indexing status for a list of pages
gsc_inspect_url	Detailed URL Inspection for a single page
gsc_sitemaps	List all sitemaps submitted for a site
gsc_audit	Generate a complete HTML audit report for a date range

Installation

Option A — uvx (recommended, zero setup)

Run directly from PyPI, no clone or venv required:

uvx mcp-google-search-console auth      # one-time OAuth authorization
uvx mcp-google-search-console            # start the MCP server

Option B — pipx

pipx install mcp-google-search-console
mcp-google-search-console auth
mcp-google-search-console

Option C — From source

git clone https://github.com/acamolese/google-search-console-mcp.git
cd google-search-console-mcp
uv venv && uv pip install -e .
.venv/bin/mcp-google-search-console auth

Configuration

1. Google Cloud setup

1. Google Cloud Console → create a project
2. Enable the Google Search Console API
3. APIs & Credentials → Create Credentials → OAuth 2.0 Client ID → Desktop app
4. Download the JSON

2. Provide the OAuth client credentials

You have three ways, pick whichever fits your setup. The server reads them in this order:

A — Environment variables (best for headless, CI, Docker, hosted MCP):

export GSC_CLIENT_ID="xxxxxxxxxxxx.apps.googleusercontent.com"
export GSC_CLIENT_SECRET="GOCSPX-xxxxxxxxxxxxxxxx"
export GSC_REFRESH_TOKEN="1//0xxxxxxxxxxxxxxxx"

With these three variables set, the server is fully stateless: no files are read or written.

B — XDG config directory (recommended for local desktop usage):

Save the OAuth client JSON as:

~/.config/mcp-google-search-console/oauth_credentials.json

Then run the interactive authorization flow:

mcp-google-search-console auth

This opens a browser, captures the OAuth consent and saves the refresh token to ~/.config/mcp-google-search-console/token.json. On Linux and macOS the path honors $XDG_CONFIG_HOME if set.

C — Legacy per-project directory (backward compatibility only):

Place files under ./credentials/oauth_credentials.json and ./credentials/token.json in the working directory where the server is launched. This mode is still supported for older setups but not recommended.

Client configuration

All examples below assume you installed with uvx. Adjust the command if you used pipx (mcp-google-search-console) or cloned from source (/path/to/.venv/bin/mcp-google-search-console).

Claude Code

Edit ~/.claude/.mcp.json:

{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"]
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"]
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (or the project-local .cursor/mcp.json):

{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"]
    }
  }
}

Zed

Add to your Zed settings.json under context_servers:

{
  "context_servers": {
    "google-search-console": {
      "command": {
        "path": "uvx",
        "args": ["mcp-google-search-console"]
      }
    }
  }
}

Continue, Windsurf, and other MCP clients

Any MCP client that supports stdio servers can use the same pattern:

{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"]
    }
  }
}

Stateless configuration with environment variables

If you prefer not to persist anything on disk, pass credentials inline:

{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"],
      "env": {
        "GSC_CLIENT_ID": "xxxxxxxxxxxx.apps.googleusercontent.com",
        "GSC_CLIENT_SECRET": "GOCSPX-xxxxxxxxxxxxxxxx",
        "GSC_REFRESH_TOKEN": "1//0xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Usage examples

Once the MCP server is wired into your client, you can ask things like:

• "List my verified sites in Search Console"
• "Show the top 50 queries for sc-domain:example.com over the last 30 days"
• "Check if these 5 pages are indexed: ..."
• "Generate a complete audit of example.com for the period 2026-01-01 → 2026-03-31"

The gsc_audit tool writes a self-contained HTML file to ~/gsc-reports/ and returns the path. Open it in any browser.

Tips

• Use sc-domain:example.com for domain properties or https://example.com/ for URL-prefix properties.
• Available dimensions for gsc_query: query, page, country, device, date (combine with commas).
• Maximum 25,000 rows per request.

Customizing the audit report

The audit report layout uses a Jinja2 template in src/google_search_console_mcp/templates/report.html.j2 with colors and fonts driven by branding.json.

To customize without touching the package, create your own branding.json in the XDG config directory:

~/.config/mcp-google-search-console/branding.json

Example:

{
  "brand_name": "Acme SEO Studio",
  "logo": "logo.png",
  "font_family": "Poppins",
  "font_url": "https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700&display=swap",
  "colors": {
    "primary": "#ff6b35",
    "primary_dark": "#cc4a1f",
    "secondary": "#004e89",
    "accent": "#00b894",
    "danger": "#e74c3c",
    "warning": "#f39c12",
    "text": "#004e89",
    "text_muted": "#5a6c7d",
    "text_light": "#8395a7",
    "bg": "#f8f9fc",
    "surface": "#ffffff",
    "border": "#e1e8ed"
  }
}

The logo field accepts either a local file name (resolved against the XDG config dir, then the package dir) or a full URL. Local files are automatically base64-encoded into the HTML so the report stays self-contained.

You can also pass a custom branding file per report via the branding_path parameter of gsc_audit:

"Generate an audit of example.com using the branding at /path/to/client-branding.json"

Security

• Never commit oauth_credentials.json, token.json, or .env files with real secrets.
• The XDG config directory is the default storage location and is outside the repository.
• The server only requests the webmasters.readonly scope.

Troubleshooting

• 401 Unauthorized on first call: token expired or missing. Run mcp-google-search-console auth or set GSC_REFRESH_TOKEN.
• "No OAuth client credentials found": neither env vars nor files are configured. See the Configuration section.
• Browser flow fails on headless machines: skip auth entirely and export GSC_CLIENT_ID, GSC_CLIENT_SECRET, GSC_REFRESH_TOKEN as environment variables.

License

MIT