Google Search Console MCP Server — gsc-mcp-full

The complete MCP server for Google Search Console. Ask Claude, Cursor, Windsurf, VS Code, Codex or any other MCP client about your search performance, indexing and sitemaps in plain language — and get analysis back, not a spreadsheet.

37 tools · every Search Console API endpoint · the 24-hour view and hourly data · history beyond 16 months · correct numbers in every language.

Quick start · Tools · Languages · FAQ · Full docs

What you get

Works with: Claude Desktop · Claude Code · Cursor · Windsurf · VS Code (Copilot agent mode) · OpenAI Codex CLI · any MCP client over stdio or HTTP.

Tools

37 tools in 8 groups. You don't call them yourself — ask in plain language and your AI picks the right one.

🌍 merges spelling variants · 🗄️ can run on local history (any date range) · ✍️ needs write access (GSC_ALLOW_WRITE=1)

📊 Search performance

🎯 SEO opportunities

🌍 Multilingual intelligence

🗄️ Unlimited history

🔍 Indexing and URL inspection

🗺️ Sitemaps

🏠 Properties

🛠️ Utilities

Every parameter of every tool: Tool reference.

Quick start

Three steps, about ten minutes, no cost. You need a Google account with access to Search Console.

1. Create your Google credentials

Google requires every app that reads Search Console to identify itself, so you create a free "OAuth client" once.

1. Open Google Cloud Console and create a project (any name).
2. Enable the Google Search Console API for it.
3. Open Credentials → Create credentials → OAuth client ID. If asked, fill in the consent screen first: type External, any app name, your own email.
4. Choose Desktop app, create it, and Download JSON. Keep the file somewhere permanent, for example ~/gsc/client_secret.json.
5. On the consent screen page, click Publish app. Without this, Google signs you out every 7 days. No review is needed for personal use.

2. Connect your AI client

Install uv if you don't have it (one command, shown on that page). It downloads and runs the server for you — there is nothing else to install.

Then add this to your client's MCP configuration, with the path to your own file:

{
  "mcpServers": {
    "search-console": {
      "command": "uvx",
      "args": ["gsc-mcp-full"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/Users/you/gsc/client_secret.json"
      }
    }
  }
}

claude mcp add search-console -e GSC_CREDENTIALS_PATH=/Users/you/gsc/client_secret.json -- uvx gsc-mcp-full

[mcp_servers.search-console]
command = "uvx"
args = ["gsc-mcp-full"]

[mcp_servers.search-console.env]
GSC_CREDENTIALS_PATH = "/Users/you/gsc/client_secret.json"

3. Sign in and ask

Sign in once from a terminal. Your browser opens; pick the Google account that has your Search Console properties.

export GSC_CREDENTIALS_PATH=~/gsc/client_secret.json
uvx gsc-mcp-full auth      # sign in (if Google warns the app is unverified: Advanced → Continue — it's your own app)
uvx gsc-mcp-full doctor    # should list your properties

Restart your AI client and ask:

List my Search Console properties, then give me a performance overview of example.com.

Stuck? See Troubleshooting.

Optional settings worth adding to the env block: "GSC_TIMEZONE": "Europe/Berlin" for local-day reports and "GSC_LANG": "fa" (or ar, tr, ja…) if most of your queries are in one language. Prefer pip? pip install gsc-mcp-full gives you the same gsc-mcp-full command.

Things to ask

• "Run a weekly SEO report for example.com: overview, what moved, and my three best opportunities."
• "Which pages lost more than 30% of their clicks since last month, and which queries did they lose?"
• "Find keyword cannibalization and tell me which page should win each one."
• "Which page-one results have a weak click-through rate? Suggest better titles."
• "Check these 20 URLs for indexing problems."
• "Split my traffic into brand and non-brand. Brand terms: toyota, تویوتا."
• "Sync 16 months of history, then show monthly clicks for queries containing 'boiler'."

More prompts and ready-made workflows: Usage guide.

Languages

Search Console counts every distinct string as its own query. When the same search can be typed several ways, one keyword becomes several small rows:

Tools marked 🌍 merge these before analysing, with rules written for each script. The text you see is never altered; only the grouping changes. Two levels: standard merges the same word typed differently, loose also merges near-spellings.

26 writing systems are recognised. English-only sites lose nothing: case, separators and spacing variants are merged for them too — while c++, c# and .net stay distinct, and 3.5 is never 35.

For Chinese, Japanese and Thai, top_terms uses a real word segmenter when you install the extra — uvx --from "gsc-mcp-full[zh]" gsc-mcp-full (or [ja], [th], [all]). The reasoning behind every rule: Languages guide.

History beyond 16 months

Google deletes Search Console data after 16 months and limits how many rows one request returns. sync_history stores each day in a local SQLite file, so both limits stop applying from the day you start.

uvx gsc-mcp-full sync example.com --days 480     # first run: everything Google still has
uvx gsc-mcp-full sync example.com --days 7       # daily, from cron: only new days are fetched

Every tool marked 🗄️ accepts source="history". Details and a cron example: History guide.

Configuration

Settings are environment variables in your client's env block. Only the first is required.

Command line

gsc-mcp-full                    # run the server — what your AI client starts
gsc-mcp-full auth [--force]     # sign in with Google
gsc-mcp-full doctor             # check setup and list properties
gsc-mcp-full sync SITE --days N # store history locally
gsc-mcp-full serve --transport streamable-http --port 8000   # serve over HTTP instead of stdio
gsc-mcp-full tools              # print the tool reference

Security

• Read-only unless you say otherwise. The default sign-in cannot change anything in Search Console.
• Everything stays on your machine. The server runs locally and talks only to Google. Your sign-in is stored in a file only you can read, and is never logged.
• Write tools are locked behind GSC_ALLOW_WRITE=1 and checked on every call.
• Search queries are treated as data. Anyone can type anything into Google; nothing in your data can trigger an action.

More in the Security guide. To report a vulnerability privately, see SECURITY.md.

FAQ

Is there an official Google Search Console MCP server? Not at the time of writing (October 2026). Google publishes an MCP server for Google Analytics but not for Search Console, so community servers like this one use Google's public Search Console API.

Is it free? Yes. The server is open source under the MIT license, the Search Console API has no charge, and the Google Cloud project needs no billing account.

Which AI assistants does it work with? Any MCP client: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code in agent mode, OpenAI Codex CLI and others, over stdio or streamable HTTP.

Can it change or break my site? No. It reads Search Console reports. With write access enabled it can add or remove properties and submit or delete sitemaps in Search Console — nothing on your website itself.

How is it different from exporting to a spreadsheet? You ask a question and get the answer. The server fetches, merges spelling variants, runs the analysis and returns a short table, capped so it never floods your AI's context.

Does it support Search Console's newest report options? The 24-hour view (hourly points, including preliminary data) and the hourly, daily, weekly and monthly granularity are all here: hourly_performance with hours=24, and granularity on performance_overview and history_trend. The newer split of web search into text-based and multimodal (Google Lens, Circle to Search) exists only in the Search Console UI; Google's API does not return it yet, so no MCP server can.

Does it have the Page indexing, Core Web Vitals or Links reports? No — Google does not offer those through its API, so no MCP server can. Per-URL index status is available through the inspection tools.

How far back does the data go? 16 months from Google. Without limit once you start syncing history locally.

Do I need to know Python? No. uvx runs everything; you only edit one configuration file.

Development

git clone https://github.com/mamrrez/gsc-mcp-full && cd gsc-mcp-full
uv venv && uv pip install -e ".[dev,all]"
uv run pytest        # no network or credentials needed
uv run ruff check
uv run python scripts/live_check.py   # optional: read-only check of every tool against your own property

Contributions are welcome, especially language rules and real query samples — see CONTRIBUTING.md.

License

MIT © Mohammadreza (mamrrez)

This project is not affiliated with or endorsed by Google. Google Search Console is a trademark of Google LLC.