Google Search Console

Google Search Console MCP server

Bring your search performance into the conversation.

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

Watch the film · What's new · Install · Tool reference · Try hosted getmcpads

Play the 45-second film

The film shows hosted getmcpads with sample data. Its MCP Apps, from creative galleries and alerts to Google Sheets exports and bulk launches, 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.1.0: Site allowlist and revoked-token handling · October 23, 2026

• Add the optional GSC_SITE_URLS allowlist, checked before every request, including URL Inspection where the property travels in the body. gsc_list_sites and gsc_health_check list only the allowed properties. Unset, the server prints a recommendation on stderr. It becomes required in 3.0.0.
• Refuse a GSC_SITE_URL outside GSC_SITE_URLS at startup, when both are set.
• Port the gateway's handling of a refused refresh token (invalid_grant, admin_policy_enforced): one re-authorization message naming GSC_REFRESH_TOKEN, and no further token requests until restart. A static GSC_ACCESS_TOKEN keeps working as before.
• Remove the unused authorization-code helpers. The server never ran an OAuth browser flow, and accounts.google.com is no longer in the source.
• Give the token request a deadline and bound every response body. Pagination limits are unchanged.
• Require Node.js ^22.23.4 || ^24.22.1 || >=26.12.1, warn on stderr at startup and in npm run doctor on older releases, and test Node 22, 24 and 26 in CI.
• Update @modelcontextprotocol/sdk to 1.32.1 and regenerate the lockfile.
• Publish from version tags with release.yml, which replaces publish-mcp.yml. Add Dependabot.
• No tool is added or removed: 20 read tools, no write tools.

Earlier releases

Full changelog · All releases

Source synchronization: SOURCE_SYNC.md.

Upgrade notes

Requires Node.js 22.23.4, 24.22.1 or 26.12.1, or a newer release of one of these lines. Older releases lack the October 2026 security fixes, and the server prints a warning on stderr when it starts on one. CI covers Node 22, 24 and 26.

This release makes no breaking change to the configuration. One change is announced for 3.0.0: GSC_SITE_URLS is optional in 2.x and becomes required. When set, every tool is limited to the listed properties, and GSC_SITE_URL must be one of them. When unset, the server starts as before and prints one line on stderr recommending it. The 20 tools, their schemas and the bounded reporting limits are unchanged.

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.

git clone --branch v2.1.0 --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. 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

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:

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 · Google Ads · TikTok Ads

The hosted version at 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, 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

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

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

{
  "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",
        "GSC_SITE_URLS": "sc-domain:example.com"
      }
    }
  }
}

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

Claude Code

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

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

Either the three OAuth values, or GSC_ACCESS_TOKEN. The server refuses to start with neither.

npm run doctor

Tools

Every tool is listed below. See server-card.json for complete parameter and output schemas.

20 read tools

7 resources

Security

• The client secret and refresh token are never logged, at any log level, or written to disk.
• A revoked refresh token is reported once. When Google answers invalid_grant, every later call returns the same message with the steps to authorize again, and the server stops asking Google for a token until it restarts.
• Properties can be limited. With GSC_SITE_URLS set, a call naming another property is refused before any request, and gsc_list_sites lists only the allowed properties.
• Three hosts are contacted, and only three: searchconsole.googleapis.com and www.googleapis.com for the API, oauth2.googleapis.com for the token refresh. A test fails the build if a fourth host appears in the source.
• No fetch follows a redirect. Every outbound call sets redirect: "error", so a redirect cannot forward a bearer token or client secret to another host. A test fails the build if any fetch omits this.
• The scope is webmasters.readonly. The token itself cannot write.
• No telemetry. The server makes no network call other than to Google.

Full policy: SECURITY.md.

Looking for a managed, multi-platform version?

Try hosted Search Console if you want to use this source without operating a local server. getmcpads also connects advertising, Search Console and GA4 through one MCP URL. Source availability and plan limits are listed on the site; connecting an account is still required.

1. Follow the Search Console connection guide.
2. Select the account or property your assistant may read.
3. Connect Claude, ChatGPT or Codex.
4. Try a read-only review: “Find which pages and queries account for a change in organic clicks. State missing data and do not change anything.”

See the current hosted tool catalogue and pricing before choosing a paid plan. This Apache 2.0 adapter remains independently useful with your own credentials.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md. Please read SECURITY.md before reporting anything security-related.

Licence

Apache License 2.0. See also NOTICE.

Google and Google Search Console are trademarks of Google LLC. This project is not affiliated with, endorsed by, or sponsored by Google LLC. It is an independent client of a public API.

MCP contracts and desktop bundle

Every tool declares read/write annotations, parameter descriptions and a structured output schema. Successful calls expose the payload as structuredContent.result; errors retain isError: true. The generated server card contains definitions only.

Run npm run bundle -- /path/to/output to build a .mcpb desktop bundle from the current catalog. Credentials are entered locally during installation. This server remains read-only.

More from getmcpads

Meta Ads · Google Ads · Google Analytics 4 · TikTok Ads · Pinterest Ads · X Ads

Maintained by Emmanuel at getmcpads. Questions: hello@getmcpads.com.