Search Console MCP

Read-only Google Search Console for AI coding agents.
Connect Cursor, Claude Desktop, or any MCP client to your GSC properties: search performance, URL inspection, and sitemaps, without leaving the editor.

• Read-only by design — OAuth scope webmasters.readonly only; no writes to Google
• Stdio by default — safe local use with Cursor and Claude
• Five focused tools — no GA4, no Indexing API, no admin clutter
• Hardened HTTP mode — optional streamable HTTP with loopback bind, body limits, and session caps

---

Table of contents

• Why use this
• Features
• Quick start
  • Agentic install prompt
  • Manual setup
• Requirements
• Installation
• Google authentication
• Connect your MCP client
• Tools reference
• Example prompts for agents
• Security
• Transports: stdio vs HTTP
• Configuration
• Troubleshooting
• Development
• Releases and npm package
• License

---

Why use this

Search Console data helps agents answer real SEO questions: which queries drive traffic, whether a URL is indexed, or what sitemaps are on file. This server exposes that data through the Model Context Protocol so tools like Cursor can call Google’s API on your behalf.

Use it when you want:

• Property lists and search analytics inside an agent session
• URL inspection results without opening the GSC UI
• A small, auditable surface (five tools) instead of a general Google analytics bundle

---

Features

| Capability | MCP tool | |------------|----------| | List properties you can access | gsc_list_sites | | Clicks, impressions, CTR, position (with dimensions) | gsc_search_analytics | | Indexing / crawl / rich-result inspection for a URL | gsc_inspect_url | | Sitemaps submitted for a property | gsc_list_sitemaps | | MCP server liveness (local Node.js, not Google) | gsc_mcp_server_ping |

Input validation — Tool arguments are validated with Zod (dates, URLs, row limits, allowlisted dimensions).

Optional TOON output — Set GSC_OUTPUT_FORMAT=toon to return compact TOON payloads (fewer tokens on search analytics and list tools).

Clear errors — Failures return MCP text with isError: true and actionable messages (auth, site_url format, quota).

---

Quick start

Agentic install prompt

Paste the block below into Cursor, Claude Code, Copilot, or Codex and ask it to run the setup. The agent should execute the steps on your machine and wire up your MCP client.

Assumptions (confirm with you before changing anything):

| Assumption | Why it matters | |------------|----------------| | Node.js 18+ | Required to build and run searchconsole-mcp | | gcloud CLI | Used for API enablement and Application Default Credentials (ADC) | | Google Cloud project | Search Console API must be enabled on a GCP project (not the same as a GSC property) | | Google account | Must already have access to the Search Console properties you care about | | User ADC (default) | Setup uses gcloud auth application-default login with webmasters.readonly, not a checked-in service account key | | Stdio transport | MCP config must not pass --transport http unless you explicitly want HTTP mode | | Absolute paths | MCP config needs the real path to dist/server.js after npm run build | | Which MCP client | Config file shape differs (Cursor/Claude Code: mcpServers; VS Code Copilot: servers; Codex: config.toml) |

The agent should ask for: install directory, GCP project ID, and which client you use.

Set up the searchconsole-mcp MCP server from https://github.com/vmandic/searchconsole-mcp on this machine end-to-end.

Before you change anything, confirm with me:
1) Which MCP client I use (Cursor, Claude Code, GitHub Copilot in VS Code, OpenAI Codex, or Claude Desktop).
2) A Google Cloud project ID where we can enable the Search Console API (or use my current gcloud default project).
3) Where to clone the repo (default: ~/source/vmandic/searchconsole-mcp or a path I choose).

Then do the following, reporting each step:

A) Prerequisites
- Verify Node.js >= 18 and gcloud are installed.
- Do not commit or paste any secrets into the repo.

B) Clone, build, test
- git clone https://github.com/vmandic/searchconsole-mcp.git into the chosen directory.
- npm install && npm run build && npm test
- Confirm dist/server.js exists.

C) Google Cloud + auth (user ADC)
- gcloud services enable searchconsole.googleapis.com --project=PROJECT_ID
- gcloud auth application-default login --scopes=https://www.googleapis.com/auth/webmasters.readonly
  (If this opens a browser, tell me to complete sign-in.)
- gcloud auth application-default set-quota-project PROJECT_ID
- Remind me: I need Search Console property access on my Google account; the GCP project only enables the API.

D) MCP client config (stdio only — no --transport http)
- Add searchconsole-mcp using command "node" and args ["ABSOLUTE_PATH/dist/server.js"], or command "searchconsole-mcp" if we npm link -g.
- Use the correct config file for my client (see the repo README "Connect your MCP client"):
  - Claude Code: prefer `claude mcp add searchconsole-mcp --transport stdio -- node ABSOLUTE_PATH/dist/server.js` first if I use multiple clients.
  - Cursor: ~/.cursor/mcp.json → mcpServers
  - VS Code Copilot: .vscode/mcp.json or user MCP config → servers, type stdio
  - Codex: ~/.codex/config.toml → [mcp_servers.searchconsole-mcp] or `codex mcp add`
- Use absolute paths only.

E) Verify
- Tell me to restart the MCP client.
- After restart, call tool gsc_mcp_server_ping (local server only, not Google).
- Call gsc_list_sites and show whether properties were returned; if auth fails, point me to README troubleshooting.

When finished, summarize: clone path, GCP project ID, config file edited, and the exact JSON/TOML or CLI command used.

---

Manual setup

Use this if you prefer to run commands yourself.

Fastest path (npm): install from @vmandic/searchconsole-mcp, complete Google authentication, then connect your MCP client with npx (see Option A — Install from npm).

1. Install and build (from source):

git clone https://github.com/vmandic/searchconsole-mcp.git
cd searchconsole-mcp
npm install
npm run build

2. Enable the API and authenticate (one-time; requires a Google Cloud project):

gcloud services enable searchconsole.googleapis.com --project=YOUR_PROJECT_ID

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/webmasters.readonly

gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Your Google user must have access to the Search Console properties you want. The GCP project does not replace that.

3. Connect a client — example for Cursor (~/.cursor/mcp.json). Using Claude Code, Copilot, or Codex too? See Connect your MCP client (set up Claude Code first if you use several).

{
  "mcpServers": {
    "searchconsole-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/searchconsole-mcp/dist/server.js"],
      "env": {}
    }
  }
}

4. Restart the client, then ask: “List my Search Console properties” (tool gsc_list_sites).

Stdio is the default (no extra flags). Logs go to stderr; JSON-RPC uses stdin/stdout.

---

Requirements

| Requirement | Notes | |-------------|--------| | Node.js | 18 or newer | | Google account | With access to the Search Console properties you care about | | Google Cloud project | Required to enable the Search Console API; used for API quota (not the same as a GSC property) | | Credentials | Application Default Credentials (user login via gcloud) or a service account JSON via GOOGLE_APPLICATION_CREDENTIALS | | MCP client | Cursor, Claude Desktop, or any client that supports stdio MCP (HTTP optional) |

Optional: Google Cloud SDK (gcloud) for the interactive ADC login flow.

---

Installation

Published on npm as @vmandic/searchconsole-mcp. The name is scoped because npm rejects unscoped searchconsole-mcp as too similar to search-console-mcp (a different package).

Option A — Install from npm (recommended)

No clone required. You still need Google authentication on the machine.

Run once (smoke test):

npx -y @vmandic/searchconsole-mcp --help
npx -y @vmandic/searchconsole-mcp --version

Global CLI (optional):

npm install -g @vmandic/searchconsole-mcp
searchconsole-mcp --help

MCP client (stdio via npx) — works in Cursor, Claude Code, Copilot, Codex, Claude Desktop. Example for Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "searchconsole-mcp": {
      "command": "npx",
      "args": ["-y", "@vmandic/searchconsole-mcp"]
    }
  }
}

After npm install -g, you can use "command": "searchconsole-mcp" and "args": [] instead.

Restart the MCP client, then try “List my Search Console properties” (gsc_list_sites).

Option B — Run from a clone (development)

git clone https://github.com/vmandic/searchconsole-mcp.git
cd searchconsole-mcp
npm install
npm test          # optional: unit tests
npm run build     # produces dist/server.js

Verify:

node dist/server.js --help
node dist/server.js --version

Point your MCP client at node /absolute/path/to/searchconsole-mcp/dist/server.js (see Connect your MCP client).

Option C — Global CLI from a local build

From a clone after npm run build:

npm link -g
searchconsole-mcp --help

Then use "command": "searchconsole-mcp" in MCP config instead of node …/dist/server.js.

---

Google authentication

The server never stores passwords. It uses Application Default Credentials (ADC): the same mechanism as gcloud and Google client libraries.

You need two different things from Google:

| What | Purpose | |------|---------| | Search Console property access | Your Google user (or service account) must be a user on the site in Search Console | | **Google Cloud projec