pip install gsc-mcp-tools

Claude Desktop

Install the latest stable package once with uv tool install gsc-mcp-tools, then copy the absolute path returned by command -v gsc-mcp-tools into the configuration:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gsc-mcp": {
      "command": "/absolute/path/to/gsc-mcp-tools",
      "env": {
        "GSC_SERVICE_ACCOUNT_PATH": "/absolute/path/to/service-account.json",
        "GSC_SKIP_OAUTH": "true",
        "GA4_PROPERTY_ID": "123456789",
        "CRUX_API_KEY": "AIza...",
        "BING_WEBMASTER_API_KEY": "<from-your-secret-store>"
      }
    }
  }
}

Remove credentials for tool families you do not use, then restart Claude Desktop. Saving the file does not restart the MCP process.

For local development, set command to the checkout's absolute executable path, for example /absolute/path/to/google-search-console-mcp/.venv/bin/gsc-mcp. Both installations expose the same 81-tool registry.

Codex

Codex starts a dedicated stdio MCP server for each task that loads it. A declaration in the user-level ~/.codex/config.toml therefore applies to every project and can leave many legitimate server processes alive while tasks remain active. Running through uvx adds a launcher process to each server.

Install the package once:

uv tool install gsc-mcp-tools
command -v gsc-mcp-tools

Then add the server only to trusted projects that need search data by creating .codex/config.toml in the project root:

[mcp_servers.gsc-mcp]
command = "/absolute/path/to/gsc-mcp-tools"
startup_timeout_sec = 60

[mcp_servers.gsc-mcp.env]
GSC_SERVICE_ACCOUNT_PATH = "/absolute/path/to/service-account.json"
GSC_SKIP_OAUTH = "true"
BING_WEBMASTER_API_KEY = "<from-your-secret-store>"

Keep this file untracked when it contains credentials. Remove provider variables you do not use. Codex loads project .codex/config.toml only for trusted projects; project configuration and precedence are documented in the official Codex configuration guide.

Do not add a global single-instance lock to a stdio server. Each client owns a separate stdin/stdout channel, so blocking later instances would break concurrent tasks instead of sharing one server safely. A shared deployment would require the streamable HTTP transport and its own authentication boundary.

Bing keyword-research endpoints are not exposed. GetKeywordStats and GetRelatedKeywords returned HTTP 400 in the redacted live canary, so their contract remains UNKNOWN.

Submission workflow and confirmation

There are nine tools that mutate remote state: five existing tools (submit_url, submit_batch, submit_sitemap, sitemaps_delete, indexnow_submit) and four Bing tools (bing_url_submit, bing_urls_submit_batch, bing_feed_submit, bing_feed_remove). Before any call, the agent must read the current state, name the exact target and volume, obtain explicit confirmation, call the tool once, then report its returned status without extrapolation.

Use this sequence for search changes:

1. Analyse measured data and state its observed window.
2. Recommend a change, separating measured facts, derived metrics and recommendations.
3. Correct the page or feed outside this MCP server.
4. Submit only after explicit confirmation and same-origin validation.
5. Verify the returned API status. An accepted request proves neither crawl nor indexation.
6. Measure a later comparable window before attributing an effect.

Current Bing runtime limits are explicit: data freshness is unknown; quota integers are not known to represent totals or remaining capacity; non-empty crawl issues, nested backlink rows and RemoveFeed remain unverified against live production data. No Bing write was executed against a production site during validation. Batch URL submission is therefore refused before mutation. bing_url_info can report a last crawl date, but it cannot provide a complete public URL Inspection verdict.

Multi-property support

To query a different GA4 property without changing the config, pass property_id directly to any GA4 or cross tool:

ga4_traffic_sources(property_id="987654321")
traffic_health_check(site="sc-domain:example.com", property_id="987654321")

# Run another registered tool
gsc-cli get-performance-overview --site https://example.com/

# Multi-value flags for list parameters
gsc-cli batch-url-inspection \
  --urls https://example.com/page-1/ \
  --urls https://example.com/page-2/ \
  --site https://example.com/

# GA4 funnel with a JSON steps array
gsc-cli ga4-funnel \
  --steps '[{"name":"Visit","event":"page_view"},{"name":"Convert","event":"purchase"}]' \
  --start-date 28daysAgo \
  --end-date today

# Keep the _meta diagnostic block in output
gsc-cli list-properties --meta

# Pipe to jq
gsc-cli get-search-analytics --site https://example.com/ | jq '.rows[:5]'

Set GSC_SERVICE_ACCOUNT_PATH for non-interactive use (same as the MCP server). To cache OAuth credentials interactively, run:

gsc-cli auth login --allow-browser

Exit codes: 0 success, 1 Google API error, 2 credential/config error or invalid arguments.

Quota note: submit-batch and submit-url use the Google Indexing API (200 req/day limit). Each gsc-cli call starts a fresh process, so cross-invocation quota tracking is not implemented. The @with_retry decorator still catches 429s, but the in-process counter resets every call.

The docs/machine-readable/ directory contains structured architecture docs designed to give any AI agent (Claude, Cursor, Copilot...) an accurate picture of the project without reading the full codebase:

• llms.txt: quick reference covering all 81 tools, module map, security rules, test patterns, and a decision tree for common tasks
• adr-index.yaml: 16 Architecture Decision Records reconstructed from git history
• code-map.yaml: full module/test/dependency map
• constraints.yaml: forbidden patterns (no stdlib XML on external input, no pickle for tokens, no unvalidated URLs in sitemap fetch...) and required patterns
• tech-decisions.yaml: stack decisions by domain (auth, retry, output contract, packaging...)

Load llms.txt via your AI context or reference it in your CLAUDE.md with @docs/machine-readable/llms.txt.

Development

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v

851 tests at this branch baseline, all mocked with no real external API calls.

Troubleshooting

uvx gsc-mcp-tools launches but no tools appear in Claude Desktop

Fully quit Claude Desktop (Cmd+Q) and reopen it. Saving the config file is not enough; the MCP process is only started on launch.

Codex keeps many gsc-mcp-tools processes alive

Check whether gsc-mcp is declared in user-level ~/.codex/config.toml. Move it to project-level .codex/config.toml when it is not needed in every task, and configure the executable installed by uv tool install instead of uvx. Restart Codex after changing the configuration; already-running tasks keep the server configuration they loaded at startup.

GSC_SERVICE_ACCOUNT_PATH is set but auth fails

Use an absolute path. Relative paths and ~/ tilde expansion are not resolved. Check with echo $GSC_SERVICE_ACCOUNT_PATH that the value is a full /Users/... path.

GA4 tools return "property_id required"

Either set GA4_PROPERTY_ID in your config env block, or pass property_id directly to the tool call. The env var is the default; the parameter overrides it per call.

crux_page_vitals or crux_history returns "CRUX_API_KEY not set"

CrUX tools require a separate Google API key (not the service account) with the Chrome UX Report API enabled. Create one in Google Cloud Console under Credentials, enable the API, then set CRUX_API_KEY=AIza... in your config.

Indexing API returns 403 on submit_url

The service account needs Owner-level access on the GSC property, not just Full access. Go to Search Console Settings > Users and permissions, find the service account email, and upgrade its role to Owner.

submit_batch quota warning at 180/200

The Indexing API default quota is 200 requests per day per GCP project. The tool warns at 180. To increase it, request a quota increase in Google Cloud Console under APIs & Services > Quotas.

GSC data is private. No web search agent can read it.

Given "which of my pages are wasting impressions with zero clicks?", an AI without API access has two honest options: admit it cannot answer, or guess from publicly visible signals. Neither is a diagnosis.

With this server, Claude pulls the actual numbers: /projects/ at position 10.1 with 87 impressions and 0 clicks, CTR benchmark 2.3% at that rank. That is the concrete gap between "you should optimize your meta titles" (available from any AI with internet access) and "your /projects/ page has 87 impressions and 0 clicks, rewrite the title" (requires your numbers).

Some tasks work without private data: checking indexation with site:, parsing sitemap structure, reading robots.txt. For those, any web-capable agent gets you there. But for anything that requires private GSC metrics (traffic drops, striking-distance queries, CTR anomalies, Indexing API submissions), there is no substitute for API access.

The server also handles Google and Bing API mechanics: isolated credentials, bounded retries, same-origin checks for Bing writes, true HTTP batch for Google indexing requests, and structured JSON output across all 81 tools. The two providers keep distinct position semantics and expose uncertainty instead of forcing incomparable data into one claim.

Why this implementation exists

Two projects shaped the approach here. AminForou/mcp-gsc (Python, 1k+ stars) has strong search analytics and handles OAuth and Service Account auth cleanly, but does not include the Google Indexing API at all. Suganthan-Mohanadasan/Suganthans-GSC-MCP (Node.js) adds the Indexing API but implements submit_batch as a sequential loop with a 100ms delay between requests, not a real HTTP batch, and mixes plain-text and JSON outputs with no retry logic.

This project takes the auth and SEO patterns from the first, the Indexing API scope from the second, and closes the gaps in both. Python was the natural choice: google-api-python-client ships service.new_batch_http_request() natively, which makes true HTTP multipart batching possible without reimplementing the wire format by hand.