# Searchconsole Mcp

> A Google Search Console APIs LLM MCP built with JavaScript.

- **Type:** MCP server
- **Install:** `agentstack add mcp-vmandic-searchconsole-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vmandic](https://agentstack.voostack.com/s/vmandic)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vmandic](https://github.com/vmandic)
- **Source:** https://github.com/vmandic/searchconsole-mcp
- **Website:** https://github.com/vmandic/searchconsole-mcp

## Install

```sh
agentstack add mcp-vmandic-searchconsole-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://search.google.com/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](https://modelcontextprotocol.io) 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](https://github.com/toon-format/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](https://cloud.google.com/docs/authentication/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](https://www.npmjs.com/package/@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):

```bash
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)):

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

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

```bash
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).

```json
{
  "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](https://developers.google.com/webmaster-tools/v1/prereqs); used for API quota (not the same as a GSC property) |
| **Credentials** | [Application Default Credentials](https://cloud.google.com/docs/authentication/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](https://cloud.google.com/sdk) (`gcloud`) for the interactive ADC login flow.

---

## Installation

Published on npm as [**`@vmandic/searchconsole-mcp`**](https://www.npmjs.com/package/@vmandic/searchconsole-mcp). The name is scoped because npm rejects unscoped `searchconsole-mcp` as too similar to [`search-console-mcp`](https://www.npmjs.com/package/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):**

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

**Global CLI (optional):**

```bash
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`):

```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)

```bash
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:

```bash
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`:

```bash
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](https://search.google.com/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](https://developers.google.com/webmaster-tools/v1/prereqs) require a Cloud project with the API turned on.

### Google Cloud project (required)

1. Create or pick a project in [Google Cloud Console](https://console.cloud.google.com/).
2. Enable the API (once per project):

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

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

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

```bash
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)

```bash
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:

```bash
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](https://github.com/googleanalytics/google-analytics-mcp) on the same machine, you can request multiple scopes in one login:

```bash
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](https://code.claude.com/) 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)**

```bash
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:

```json
{
  "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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-vmandic-searchconsole-mcp
- Seller: https://agentstack.voostack.com/s/vmandic
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.