Google Search Console MCP Server & CLI

Google Search Console MCP server and CLI for Claude Code, Codex and AI agents. 19 tools for search analytics, URL inspection, sitemaps and property verification.

One install gives you both surfaces, the same 19 tools under the same names, from the same server, so they cannot drift apart.

Give any AI agent real access to what Google Search actually recorded about your sites. Queries, pages, impressions, rankings, indexing, sitemaps, from Claude Code, Claude Desktop, claude.ai, Cursor, Codex, or any MCP client.

Built by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI.

Two ways to use it

Command line

google-search-console-cli runs every tool as a command. Agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal, a script or a cron job:

google-search-console-cli                                   # every command, one line each
google-search-console-cli list-sites                        # the exact property strings
google-search-console-cli top-queries --site sc-domain:example.com --limit 10
google-search-console-cli striking-distance --site sc-domain:example.com
google-search-console-cli top-pages --site sc-domain:example.com --json --select rows.page,rows.clicks
google-search-console-cli delete-sitemap --site sc-domain:example.com --sitemap-url https://example.com/old.xml --confirm
google-search-console-cli which submit a sitemap            # find the command for a task
google-search-console-cli <command> --help                  # what any command takes

--confirm is the shell spelling of the confirmation deleting a property or a sitemap needs. --json gives JSON, --compact puts it on one line, --select keeps only the fields you name, and --agent turns on all of it for a script. Exit codes are 0 ok, 1 unexpected, 2 usage or a refused write, 3 not found, 4 auth, 5 API, 7 rate limited and 10 nothing configured, so a script branches on the number.

google-search-console-cli schema <command> prints the exact JSON Schema an MCP client receives for that tool.

MCP server, for AI agents

google-search-console-mcp is what Claude Code, Claude Desktop, Cursor and the rest launch. You never run it by hand:

claude mcp add google-search-console -- npx -y @thenavidm/google-search-console-mcp-cli@latest

In Claude Desktop, the .mcpb extension installs on a double click. Section 4 has every other client.

What each costs

Both surfaces are the same program with the same 19 tools. The difference is when the model pays for them. Measured in Claude Code:

Claude Code's tool search is on by default: it sends only the tool names and the server instructions, and loads a tool's full definition when the model reaches for it. An app that loads every tool up front pays the first line on every message, whether Search Console comes up or not. With the skill added, Claude Code also lists its one-line description, about 190 tokens.

To spend less, turn the server off when you are not using it, which in Claude Code is the /mcp panel. GSC_READ_ONLY=1 takes the 5 write tools off the list, leaving 14. Or install the CLI and add the server on the days it earns its place.

Measured on 2026-10-05 against 0.2.2, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, once with ENABLE_TOOL_SEARCH=false and once with the default, the difference read from the API's own usage figures; SKILL.md the same way) and Codex 0.159.3 on gpt-6.1-sol:

The task was "find the command for the queries a site ranks just off page one, and the flags it requires". Every tool loaded costs less because each tool no longer repeats $schema and an execution block. Over the CLI, every 0.2.2 run read the general help, the command list and the command's help, three requests that each carry the conversation so far, and every 0.3.0 run read the general help and asked which, which answered with the command's help: two. Other apps and models count tokens a little differently, and tool-list characters divided by four are not API usage.

Related MCP server: Google Search Console MCP Server

Contents

1. What you can ask it 💬

• Which queries lost the most clicks this month compared to last?

• Show me pages ranking between 5 and 20. Which are closest to page one?

• Why is this URL not showing up in Google?

• What are my top queries for the blog, US only?

• Is Google still reading my sitemap?

• We just launched 30 pages. Check which ones are indexed.

• Which of my pages get impressions but almost no clicks?

• Add this new domain to Search Console and verify it.

• Compare mobile against desktop for the last quarter.

The first one is the point. "What changed" is the question anyone actually has, and Search Console's own interface makes you export two reports and join them in a spreadsheet to answer it. Here it is one call, with the deltas already computed.

2. Quick install ⚡

Node 22 or newer. Nothing else.

npx -y @thenavidm/google-search-console-mcp-cli@latest --version

That is the whole install. npx fetches it on demand, so there is nothing to update later.

For the CLI as a command you or your agent can run anywhere, install it once:

npm install -g @thenavidm/google-search-console-mcp-cli
google-search-console-cli

3. Setup 🔑

You need a Google credential. Google does not hand out Search Console access without a Google Cloud project, so there is a real setup here: about five minutes, once.

The full walkthrough is in INSTALL.md. Every click, both routes, and what each error means.

Have an agent do it

The agent cannot sign in to Google for you. Only you can. What it can do is walk you through the console, wire up your client config, and check the connection.

Paste this into Claude Code, Cursor, or any agent with terminal access:

Set up @thenavidm/google-search-console-mcp-cli for me.

1. Read https://github.com/thenavidm/google-search-console-mcp-cli/blob/main/INSTALL.md
2. Walk me through the Google Cloud steps one at a time. Stop and wait
   for me after each one. Do not skip the part about publishing the
   OAuth app: it is why these break after a week.
3. When I give you the client ID and secret, run `login` and then
   `doctor`, and tell me what properties it can see.
4. Then add it to my MCP client config.

The one step people skip

While your OAuth app's publishing status is Testing, Google issues refresh tokens that expire after 7 days. Everything works, and then a week later it stops for no visible reason.

Click Publish app on the Audience page during setup. The setup guide covers where that is and why the verification warning does not apply to you.

Signing in

export GSC_CLIENT_ID="...apps.googleusercontent.com"
export GSC_CLIENT_SECRET="GOCSPX-..."

npx -y @thenavidm/google-search-console-mcp-cli@latest login

A browser opens, you pick your Google account, and the refresh token is saved to ~/.google-search-console-mcp/tokens.json.

For a server or CI with no browser, use a service account instead. Both routes are in the setup guide.

4. Connect your client 🔌

Claude Code

claude mcp add google-search-console \
  -e GSC_CLIENT_ID=your-client-id \
  -e GSC_CLIENT_SECRET=your-client-secret \
  -- npx -y @thenavidm/google-search-console-mcp-cli@latest

Add --scope user to make it available in every project rather than just this one.

Claude Desktop

The short way: download the .mcpb extension from the latest release and double-click it. It carries its own dependencies, so there is no config file to edit and nothing to install first. Sign in once with npx -y @thenavidm/google-search-console-mcp-cli login first, or pick a service account key when Claude Desktop asks.

The long way, if you would rather edit the config yourself:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "@thenavidm/google-search-console-mcp-cli@latest"],
      "env": {
        "GSC_CLIENT_ID": "your-client-id",
        "GSC_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Tip Claude Desktop does not inherit your shell PATH. If it cannot find npx, use the absolute path from which npx.

Quit Claude Desktop completely and reopen it. Closing the window is not enough.

Cursor

.cursor/mcp.json, same JSON shape as Claude Desktop, same mcpServers key.

Windsurf

~/.codeium/windsurf/mcp_config.json, same shape, same mcpServers key.

VS Code

.vscode/mcp.json. The key here is servers, not mcpServers, and each entry needs "type": "stdio".

{
  "servers": {
    "google-search-console": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/google-search-console-mcp-cli@latest"],
      "env": {
        "GSC_CLIENT_ID": "your-client-id",
        "GSC_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.google-search-console]
command = "npx"
args = ["-y", "@thenavidm/google-search-console-mcp-cli@latest"]

[mcp_servers.google-search-console.env]
GSC_CLIENT_ID = "your-client-id"
GSC_CLIENT_SECRET = "your-client-secret"

Gemini CLI

~/.gemini/settings.json, same mcpServers shape as Claude Desktop.

Everything else

Any stdio MCP client needs the same three things: the command npx, the args array, and the env block.

To disconnect, remove the entry from your MCP client's config, then run logout your@email.com to delete the local token. Then revoke Google's side at myaccount.google.com/permissions. That is the half that matters: deleting the local file leaves a live grant behind.

5. Check it worked 🩺

npx -y @thenavidm/google-search-console-mcp-cli@latest doctor

It reports the Node version, which credential is in use, whether a token can actually be minted, how many properties that account reaches, whether verification is available, and which safety switches are on.

  ✓ Signed in          you@example.com, stored at ~/.google-search-console-mcp/tokens.json
  ✓ OAuth client       GSC_CLIENT_ID and GSC_CLIENT_SECRET are set, so tokens refresh automatically
  ✓ Token              live for you@example.com, by oauth
  ✓ Search Console     4 properties, 4 writable. First: sc-domain:example.com

It exits 0 when everything works, 1 when a check fails, and 10 when nothing is signed in.

Two things account for almost every failure, and doctor names both: zero properties means you signed in with the wrong Google account, and a refresh failure a week after setup means the OAuth app is still in Testing.

6. Tools 🛠️

Nineteen tools. The five marked ● are writes and disappear under GSC_READ_ONLY=1; the two deletes also disappear under GSC_ALLOW_DESTRUCTIVE=0.

Search performance

compare_periods and striking_distance are the two you cannot get from the API in one call and cannot build in the UI at all without exporting to a spreadsheet.

Indexing

Sitemaps

Properties

Verification

Verification needs the browser sign-in. A service account cannot verify a property, because verification is tied to a human Google account.

7. Working safely 🛡️

Writes work by default. Publishing a sitemap is the point of having the tool, and a server where every write needs a flag just teaches you to set the flag once and forget it.

Three mechanisms do the job instead.

Confirmation on the two irreversible tools, delete_site and delete_sitemap. Over MCP a person approves each call: Claude Code (2.1.246 and later) shows its own prompt, and a client that can show forms asks with an approval form whose one box starts unticked. Where a client can do neither, the model's confirm: true still counts, and GSC_CONFIRM=model makes it enough everywhere. In a terminal the flag is --confirm, which --agent never adds. Not on submit_sitemap or add_site: both are trivially undone, and asking for confirmation on everything trains the reflex that defeats asking at all.

GSC_READ_ONLY=1 removes writes entirely. They are left off the tool list, and refused if called anyway. A model cannot call a tool it cannot see. This is the right setting for an agent working unattended.

GSC_ALLOW_DESTRUCTIVE=0 keeps submit_sitemap and add_site while dropping the two deletes from the list.

GSC_AUDIT_LOG=<path> writes one JSON line per attempted write, allowed and refused alike, with who approved it, then whether it was done or failed. Arguments are not logged, so no token reaches it.

Every tool carries MCP annotations so your client can decide what to auto-approve:

On prompt injection. A search query is whatever a stranger typed into Google, and a title read through URL inspection is whatever that page says. Both reach your model's context. Text from those fields is framed as data rather than instructions, which helps and is not a guarantee. For an agent running unattended against sites you do not control, GSC_READ_ONLY=1 is the real defence.

8. What Search Console actually does 📊

The things that cost people an afternoon.

Data lags two to three days. Ask for "the last 7 days ending today" and the last few are empty or partial. Every tool here with a default window already ends three days back and tells you the dates it used. Pass data_state: "all" to query_search_analytics if you want the partial days anyway.

The query breakdown never sums to the site total. Google withholds rare queries to protect the people who typed them, so a per-query report always shows fewer clicks than the property total for the same window. That gap is anonymised traffic, not missing traffic, and it is normally larger than people expect.

A property is not a website. https://example.com/ and sc-domain:example.com are two different properties with different data, and https://example.com without the trailing slash is not a valid property string at all. Passing the wrong shape returns "User does not have sufficient permission", which reads like a scope problem and sends people back to the consent screen. Run list_sites and copy exactly. These tools normalize what they can.

Average position is a rank, so lower is better. Position moving from 8 to 5 is an improvement. compare_periods returns position_delta already signed so positive always means better, because "position went up" is ambiguous in the exact place it matters most.

There is no "request indexing" endpoint. The button exists in the UI; Google exposes no API behind it. Resubmitting a sitemap is the only recrawl signal available programmatically. Anything claiming otherwise is either using the Indexing API, which only works for job postings and livestreams, or it is not doing what it says.

About 16 months of history. Ask for more and you get what exists, silently.

Quotas are per property, not per token. Roughly 1200 search analytics queries per minute, and about 2000 URL inspections per day with 600 per minute. inspect_urls paces itself, but a loop over a large site will hit the daily ceiling.

Discover and Google News are different surfaces. Pass type: "discover" and there is no query dimension and no device dimension at all. Asking for one returns an error rather than empty rows.

9. Your data 🔐

There is no backend. Nothing is sent anywhere except Google.

GSC_TOKEN_STORE moves the token file. logout <email> deletes an entry from it, accounts lists them, and myaccount.google.com/permissions revokes Google's side, which is the half that actually matters.

Search Console data is read on demand and never cached to disk.

Settings

The program reads the environment directly. It does not load .env files.

Credentials, in the order they are tried

Safety

Tuning

10. Running it on a server 🌐

claude.ai runs connectors from Anthropic's cloud, not from your machine, so it cannot start a local command. It needs a public HTTPS URL, which means the HTTP transport.

npx -y @thenavidm/google-search-console-mcp-cli@latest --http --port 8000

That binds 127.0.0.1. To bind anything else you must set GSC_HTTP_TOKEN, and the server refuses to start without it:

export GSC_HTTP_TOKEN="$(openssl rand -hex 32)"
npx -y @thenavidm/google-search-console-mcp-cli@latest --http --host 0.0.0.0 --port 8000

The refusal is deliberate. Whatever can reach that port can read your site's entire search history and delete its properties. A page from another site is refused too, unless GSC_HTTP_ALLOWED_ORIGINS lists it.

Then in claude.ai: Customize, Connectors, +, Add custom connector, and paste the HTTPS URL ending in /mcp. On Team and Enterprise an owner adds it under Organization settings, Connectors first.

There is a Dockerfile if you would rather run it that way.

11. Troubleshooting 🔧

Start with doctor. It checks each failure mode separately and names the fix. Access tokens last an hour and refresh on their own, so an expired token is never the problem by itself.

12. FAQ

An MCP server is a standard way to give an AI assistant real access to a tool, so it can act instead of guessing. You install it once, your assistant gains a set of tools, and it works in Claude, Cursor, Codex and anything else that speaks MCP.

Without one, an assistant asked about your search traffic can only tell you how Search Console works in general. With one, it reads your actual numbers.

google-search-console-cli is the same program as the MCP server, run as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal, a script or a cron job. Every tool is a command with dashes, so top_queries runs as google-search-console-cli top-queries.

Use the MCP server in an app with no terminal, like Claude Desktop's chat. Use the CLI anywhere commands run: an agent like Claude Code, Codex or OpenCode, a script or a cron job. The MCP server's tools take up context on every message, and the CLI costs nothing until it runs.

Google Search Console is Google's free tool for site owners. It shows what people searched before they landed on your site, which pages Google shows and where they rank, which pages Google has and has not indexed, and what it thinks is broken.

It is the only place Google tells you any of this. Analytics tells you what people did once they arrived; Search Console tells you what happened in Google before that.

You need to be comfortable pasting commands into a terminal and clicking through a few pages in Google Cloud. The setup guide covers every click, and the prompt in section 3 hands the whole thing to an agent that walks you through it one step at a time.

The Google Cloud part is the hard bit, and it is a one-time five minutes.

There is no backend and no telemetry. The server runs on your machine, talks to Google, and returns the answer to your AI client. The only thing written to disk is your refresh token, at ~/.google-search-console-mcp/tokens.json with 600 permissions.

Your search data does reach whichever AI model you are using, because that is the point. If that matters for a particular site, do not connect it.

There are two things the UI cannot do at all, and one it does slowly.

Comparing two periods with per-query deltas is an export-and-spreadsheet job in the UI. Here it is one call. Finding every query ranking between 5 and 20, ordered by impressions, is the same story.

Everything else it does faster: checking 30 URLs after a launch is 30 clicks in the UI and one call here.

Two tools can delete something. delete_site removes a property from your account, and delete_sitemap stops Search Console tracking a sitemap. Both refuse to run until confirmed: over MCP a person approves each call in the client, and in a terminal it takes --confirm.

Neither touches your website, and neither removes anything from Google's index. delete_site loses your account's access to that property's history until it is re-added and re-verified.

Set GSC_READ_ONLY=1 and both disappear from the tool list entirely.

It costs nothing. The server is MIT licensed, Search Console is free, and the Google Cloud project you create is free. There is no card required and no billing to enable.

Your AI assistant costs whatever it already costs.

It works with any MCP client. Section 4 has copy-paste config for Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex CLI and Gemini CLI.

claude.ai is the one that works differently: it runs connectors from Anthropic's cloud rather than your machine, so it needs the HTTP transport and somewhere to host it. See section 10.

You can connect as many as you like. Run login again with a different account and both are stored. Every tool takes an optional account argument taking an email, and list_accounts shows what is signed in.

Useful when your own sites and a client's sit under different Google logins.

Google offers no such endpoint. "Request indexing" exists in the Search Console UI and has no API behind it, and the Indexing API that does exist only accepts job postings and livestreams.

Resubmitting a sitemap is the only recrawl signal available programmatically, which is what submit_sitemap is for.

Questions

Run into a problem or have a question? Open an issue and I will help.

Built by

Navid Moazzez

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.

Dependencies

License

MIT. See LICENSE.

Not affiliated with, endorsed by, or sponsored by Google. Google, Google Search Console and Google Cloud are trademarks of Google LLC.

© 2026 Navid Media. Made with ❤️ by Navid Moazzez.