Searchconsole Mcp

Search Console MCP

[](https://github.com/vmandic/searchconsole-mcp/actions/workflows/ci.yml) [](https://github.com/vmandic/searchconsole-mcp/releases/latest) [](https://www.npmjs.com/package/@vmandic/searchconsole-mcp) [](LICENSE) [](package.json) [](https://modelcontextprotocol.io)

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](#why-use-this)
• [Features](#features)
• [Quick start](#quick-start)
• [Agentic install prompt](#agentic-install-prompt)
• [Manual setup](#manual-setup)
• [Requirements](#requirements)
• [Installation](#installation)
• [Google authentication](#google-authentication)
• [Connect your MCP client](#connect-your-mcp-client)
• [Tools reference](#tools-reference)
• [Example prompts for agents](#example-prompts-for-agents)
• [Security](#security)
• [Transports: stdio vs HTTP](#transports-stdio-vs-http)
• [Configuration](#configuration)
• [Troubleshooting](#troubleshooting)
• [Development](#development)
• [Releases and npm package](#releases-and-npm-package)
• [License](#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-cloud-project-required)) | | 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](#google-authentication), then [connect your MCP client](#connect-your-mcp-client) with npx (see [Option A — Install from npm](#option-a--install-from-npm-recommended)).

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](#google-cloud-project-required)):

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](#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](#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](#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 project | Enables the Search Console API and attributes quota/billing for API calls |

Having a site in Search Console is not enough on its own. Google’s API prerequisites require a Cloud project with the API turned on.

Google Cloud project (required)

1. Create or pick a project in Google Cloud Console.
2. Enable the API (once per project):

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

Or: APIs & Services → Library → search Google Search Console API → Enable.

1. After ADC login, set the quota project if Google asks for one (common with user credentials):

gcloud auth application-default set-quota-project YOUR_PROJECT_ID

YOUR_PROJECT_ID is the Cloud project ID (e.g. my-seo-tools), not a Search Console property URL.

Service accounts must be created inside this same Cloud project. The JSON key you download is tied to that project; you still add the service account email as a user on each GSC property.

This MCP server does not ask you for a project ID in config. GoogleAuth picks it up from ADC, GOOGLE_CLOUD_PROJECT, or gcloud config set project.

Personal / laptop setup (most common)

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

That scope is enough for this server. Your Google user must already have access to the relevant Search Console properties, and the Search Console API must be [enabled on a Cloud project](#google-cloud-project-required) (see above).

Service account

Set a key file path:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

The service account must be added as a user on each GSC property (Settings → Users and permissions).

Sharing ADC with Analytics MCP

If you use Google’s Analytics MCP on the same machine, you can request multiple scopes in one login:

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

This server only needs webmasters.readonly; extra scopes are optional for your workflow.

---

Connect your MCP client

Every client runs the same local Node.js MCP server (searchconsole-mcp). That process talks to Google Search Console on your behalf. The client (Cursor, Claude Code, Copilot, Codex) only spawns the server and passes tool calls over stdio.

Before you connect any client

1. Complete [Google authentication](#google-authentication) (ADC) once on the machine.
2. Choose how to start the server:

• npm: [Option A](#option-a--install-from-npm-recommended) — npx -y @vmandic/searchconsole-mcp or global searchconsole-mcp
• Clone: run npm run build so dist/server.js exists, then use an absolute path in config (or npm link -g / Option C)

If you use more than one client, set up Claude Code first. You will reuse the same binary and credentials; doing auth and paths once avoids confusion when you add Cursor, Copilot, or Codex.

| Client | Config location | Config key | |--------|-----------------|------------| | Claude Code | CLI, ~/.claude.json, or project .mcp.json | mcpServers | | Cursor | ~/.cursor/mcp.json | mcpServers | | GitHub Copilot (VS Code) | .vscode/mcp.json or user MCP config | servers | | OpenAI Codex | ~/.codex/config.toml | [mcp_servers.] | | Claude Desktop | OS-specific Claude config | mcpServers |

All examples below use stdio (default). Do not pass --transport http unless you intend [HTTP mode](#transports-stdio-vs-http).

---

1. Claude Code (set up first)

Claude Code is Anthropic’s terminal coding agent. Configure searchconsole-mcp here first if you plan to use multiple tools on one machine.

Option A — CLI (quick)

claude mcp add searchconsole-mcp --transport stdio -- \
  node /absolute/path/to/searchconsole-mcp/dist/server.js

Check: claude mcp list (or /mcp in the Claude Code session).

Option B — Project file (team-friendly)

Add .mcp.json at the project root:

{
  "mcpServers": {
    "searchconsole-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/search

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vmandic](https://github.com/vmandic)
- **Source:** [vmandic/searchconsole-mcp](https://github.com/vmandic/searchconsole-mcp)
- **License:** MIT
- **Homepage:** https://github.com/vmandic/searchconsole-mcp

Install and usage instructions live in the source repository linked above.