google-search-console-mcp-server

<div align="center">

# Google Search Console MCP server

### Bring your search performance into the conversation.

Investigate queries, pages, indexing and sitemaps through a read-only MCP server.

[![Release](https://img.shields.io/github/v/release/get-mcp-ads/google-search-console-mcp-server?color=2448e5)](https://github.com/get-mcp-ads/google-search-console-mcp-server/releases/latest)
[![CI](https://github.com/get-mcp-ads/google-search-console-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/get-mcp-ads/google-search-console-mcp-server/actions/workflows/ci.yml)
[![Smithery](https://smithery.ai/badge/hello-6k33/getmcpads-google-search-console)](https://smithery.ai/servers/hello-6k33/getmcpads-google-search-console)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A522.12-brightgreen.svg)](package.json)

[Watch the demo](https://www.getmcpads.com/home/film/get-mcp-ads-film-1080p.mp4) · [What's new](#whats-new) · [Install](#install-this-release) · [Tool reference](#tools) · [Try hosted getmcpads](https://www.getmcpads.com/tools/search-console?utm_source=github&utm_medium=readme&utm_campaign=google-search-console)

[![Watch the getmcpads product demo: campaign review in Claude](https://www.getmcpads.com/home/film/poster-rich.webp)](https://www.getmcpads.com/home/film/get-mcp-ads-film-1080p.mp4)

**[Play the 27-second product film](https://www.getmcpads.com/home/film/get-mcp-ads-film-1080p.mp4)**

</div>

The film demonstrates hosted getmcpads with staged data. Its creative galleries and MCP Apps interface belong to the hosted product. This repository provides the standalone native API tools.

**20 read tools** · Read-only by design.

Run locally with your own platform credentials and a client that supports stdio MCP, such as Claude Desktop, Claude Code or Cursor. Your requests go directly to the platform. For managed connections, including supported ChatGPT setups, use the hosted option.

## What's new

**[v2.0.1: Native tools and security update](https://github.com/get-mcp-ads/google-search-console-mcp-server/releases/tag/v2.0.1) · September 20, 2026**

- Bound automatic pagination to four pages, 100,000 rows and a 30-second total deadline.
- Expose pagination and truncation diagnostics while preserving hourly data and native metadata.
- Remove provider error bodies from logs and errors; bound search-type comparison fan-out.
- Require Node.js 22.12 or newer and check Node 22/24 in CI.
- Update vulnerable dependencies and regenerate the MCP catalog.

[Full changelog](CHANGELOG.md) · [Source synchronization details](SOURCE_SYNC.md) · [All releases](https://github.com/get-mcp-ads/google-search-console-mcp-server/releases)

### Upgrade notes

Requires **Node.js 22.12 or newer**. CI covers Node 22 and 24. Version 2.0.1 drops Node 18 and 20 support. Hosted creative integrations and MCP Apps UI are outside this release.

## Install this release

This is a GitHub source release. npm and MCP Registry versions are published separately. The commands below select this exact version; unpinned `npx` examples later in this document select the version currently available on npm.

```bash
git clone --branch v2.0.1 --depth 1 https://github.com/get-mcp-ads/google-search-console-mcp-server.git
cd google-search-console-mcp-server
npm ci
npm run build
```

Configure your MCP client to run `node` with the absolute path to `dist/cli.js` and the platform credentials documented below.

> **Prefer a managed connection?** [Use Google Search Console with hosted getmcpads](https://www.getmcpads.com/tools/search-console?utm_source=github&utm_medium=readme&utm_campaign=google-search-console). Connect your account, select the data your assistant may access and use the hosted MCP connection. See the site for current features and plans.

## What you get

| | |
|---|---|
| **20 read tools** | Search Analytics, sites, sitemaps, URL Inspection, and analyses built on top of them |
| **SEO analyses, not just an API wrapper** | Cannibalisation detection, query clustering, wins and losses between periods, indexation watchlists, large-site sampling plans |
| **7 resources** | Live catalogues the model can read: metrics, dimensions, filters, compatibility rules, 8 workflow recipes, read-only playbooks |
| **Quota guardrails** | Every URL Inspection call is capped at 10 URLs, so one exploratory question cannot burn a day of quota |
| **No writes at all** | Not a flag, a property of the code. See below |

### What it does beyond fetching rows

Search Console answers questions about rows. Most real questions are about **change**: which
queries did we lose, which pages compete for the same term, is indexing drifting.

These tools do that work rather than leaving it to the model:

| Tool | Question it answers |
|---|---|
| `gsc_detect_cannibalization` | Which pages compete for the same query |
| `gsc_find_losses_gains` | What we won and lost between two periods |
| `gsc_cluster_queries` | Which queries belong to the same intent |
| `gsc_compare_search_types` | How web, image, video and news differ |
| `gsc_analyze_search_appearance_trends` | How rich results evolve |
| `gsc_indexation_watchlist` | Which URLs changed indexing verdict |
| `gsc_plan_large_site_sampling` | Which URLs to inspect, when you cannot inspect them all |

---

## One thing to know before you trust a number

**Search Console returns a top N, not a site total.**

When you query with a dimension such as `query` or `page`, the API returns the highest
ranked rows up to your row limit, ordered by clicks. Summing the clicks of those rows does
**not** give you the site total: the long tail is missing, and on a large site it can be most
of the traffic.

To get a real total, query **without dimensions**. To compare periods, compare like with
like: same dimensions, same row limit, same search type.

`gsc_query_search_analytics` reports what it actually returned, and `gsc_validate_query`
checks a combination before it runs. But the arithmetic mistake is yours to avoid, and it is
the most common one in Search Console analysis.

Two other limits worth carrying in your head:

- **Roughly 16 months of history.** Anything older is gone, not slow.
- **Data settles over about three days.** `gsc_get_data_freshness` tells you what is final.

---

## Read-only, and why it stays that way

There are no write tools, and no environment variable that adds any. The Search Console API
can submit and delete sitemaps, add and remove properties, and request indexing. **This
server exposes none of that.**

The scope it asks for reflects that: `webmasters.readonly`, not `webmasters`. Even if the
model tried, the token cannot write.

Our ad platform servers, where writes make sense, do have them, guarded by a mandatory
preview:
[Meta Ads](https://github.com/get-mcp-ads/meta-ads-mcp-server) ·
[Google Ads](https://github.com/get-mcp-ads/google-ads-mcp-server) ·
[TikTok Ads](https://github.com/get-mcp-ads/tiktok-ads-mcp-server)

The hosted version at [getmcpads.com](https://www.getmcpads.com) keeps the same rule: Search
Console stays read-only there too.

---

## Getting credentials

Three values, obtained once.

### 1. OAuth client

In a [Google Cloud project](https://console.cloud.google.com/), enable the **Google Search
Console API**, then create an OAuth client under **APIs & Services → Credentials**. Choose
**Desktop app** for local use. Note the **client ID** and **client secret**.

### 2. Refresh token

Run the OAuth consent flow once, signed in as a Google account that owns or can read your
properties, and keep the **refresh token**. Request `webmasters.readonly` and nothing more.

📖 [Google OAuth for installed apps](https://developers.google.com/identity/protocols/oauth2/native-app)

**The refresh token does not expire.** Use an OAuth client dedicated to this server so you
can revoke it on its own.

For a quick trial you can set `GSC_ACCESS_TOKEN` to a short-lived token instead, but it
expires within the hour and is useless for daily work.

If setting up an OAuth client is more than you want to do for one property,
[getmcpads.com](https://www.getmcpads.com) handles the consent flow for you and gives you the
same tools behind a hosted endpoint.

### 3. Site URL, optional

Set `GSC_SITE_URL` to avoid passing it on every call. Both property forms work:

| Property type | Value |
|---|---|
| URL-prefix | `https://example.com/` (the trailing slash matters) |
| Domain | `sc-domain:example.com` |

List what you can reach with `gsc_list_sites`, and run **`gsc_health_check`** as your first
call. It verifies the credentials without printing any secret.

---

## Setup

### Claude Desktop

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

```json
{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@getmcpads/google-search-console-mcp-server"],
      "env": {
        "GSC_CLIENT_ID": "your-client-id",
        "GSC_CLIENT_SECRET": "your-client-secret",
        "GSC_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}
```

Restart Claude Desktop. Ask it: *"which queries did we lose last month?"*.

### Claude Code

```bash
claude mcp add search-console --env GSC_CLIENT_ID=... --env GSC_CLIENT_SECRET=... --env GSC_REFRESH_TOKEN=... -- npx -y @getmcpads/google-search-console-mcp-server
```

### Cursor

`.cursor/mcp.json` in your project, same shape as the Claude Desktop config above.

### From source

```bash
git clone https://github.com/get-mcp-ads/google-search-console-mcp-server.git
cd google-search-console-mcp-server
npm install && npm run build
cp .env.example .env   # then fill in your credentials
npm start
```

### Configuration

| Variable | Default | Meaning |
|---|---|---|
| `GSC_CLIENT_ID` | none | OAuth client ID |
| `GSC_CLIENT_SECRET` | none | OAuth client secret |
| `GSC_REFRESH_TO