Building a Google Search Console MCP server from scratch

Why build this instead of using an existing one

Searching for a Google Search Console MCP connector turns up a real gap: nothing official from Google or Anthropic. Claude's own Discover marketplace does list several community-built options when you search "GSC" — multiple of them, in fact, which says something about the actual demand — but every single one is third-party code from an author with no track record to check. For something that would hold OAuth access to real Search Console data, that's a meaningful trust gap, not a theoretical one. Worth noting: some of those listings are hosted connectors, meaning the vendor's own server sits between you and Google — your OAuth grant would flow through infrastructure you've never heard of, not just code you haven't audited.

The alternative built here draws a specific line: original code, built on first-party SDKs only — Anthropic's own @modelcontextprotocol/sdk for the protocol, Google's own googleapis client for OAuth and API calls. Not a hand-rolled OAuth implementation either — reusing the provider's own, audited libraries for the security-critical parts is the safer choice, not a compromise on "from scratch."

What you end up with

Four read-only tools, usable directly from a Claude Desktop chat once installed:

Scope is webmasters.readonly only — nothing it does can change anything in your Search Console account. It can look, not touch.

Setting it up, step by step

This section assumes zero prior experience with Google Cloud Console or MCP. Every command is given for both Windows and macOS/Linux where they actually differ — most don't.

Before you start: install Node.js (the LTS version) and Git if you don't already have them. Windows users: installing Git also installs Git Bash — use that instead of Command Prompt for the commands below (PowerShell works too; given separately wherever the syntax differs).

Step 1 — create a Google Cloud project

1. Go to console.cloud.google.com.
2. Top bar → project dropdown → New Project.
3. Name it anything (e.g. "gsc-mcp-server") and create it.
4. Make sure the new project is selected in the top bar before continuing.

Step 2 — enable the Search Console API

1. APIs & Services → Library.
2. Search for "Google Search Console API".
3. Click it, then click Enable.

Step 3 — configure the OAuth consent screen

This is the step most likely to trip you up if you skip a sub-step, so read this one slowly.

1. APIs & Services → OAuth consent screen.
2. User type: External — this just means "not restricted to a Google Workspace org." It stays private to you until you explicitly publish it, which personal use never requires.
3. Fill in the required fields (app name, your email as support contact) — nothing here is visible to anyone but you.
4. Scopes: add https://www.googleapis.com/auth/webmasters.readonly.
5. Test users: add your own Google account's email address — do not skip this. Miss it, and signing in later fails with Error 403: access_denied, for a reason that isn't obvious from the error itself (explained below).
6. Leave Publishing status as Testing. In Testing mode, only the emails you listed as test users can authorize the app at all, and Google's full app-verification review — a real, multi-week process — doesn't apply. It only kicks in if you publish for the general public. The "100 test users" limit you'll see mentioned is irrelevant here; this uses 1 of 100.

Step 4 — create the OAuth client credentials

1. APIs & Services → Credentials → Create Credentials → OAuth client ID.
2. Application type: Desktop app — important. Desktop-type clients get Google's automatic loopback-redirect allowance, so no redirect URI or port needs registering ahead of time.
3. Name it anything, create it.
4. Click the download icon next to the new client → Download JSON.

Step 5 — save the client secret where the server expects it

Windows (Git Bash) and macOS/Linux — identical command:

mkdir -p ~/.gsc-mcp-server
mv ~/Downloads/client_secret_*.json ~/.gsc-mcp-server/client_secret.json

Windows (PowerShell), if that's what you're using instead:

mkdir "$env:USERPROFILE\.gsc-mcp-server"
Move-Item "$env:USERPROFILE\Downloads\client_secret_*.json" "$env:USERPROFILE\.gsc-mcp-server\client_secret.json"

# macOS / Linux
ls -la ~/.gsc-mcp-server/

# Windows PowerShell
dir "$env:USERPROFILE\.gsc-mcp-server\"

Step 6 — clone, install, and authorize

Same commands on every OS — git and npm don't differ by platform:

git clone https://github.com/learnwithbadridutta/gsc-mcp-server.git
cd gsc-mcp-server
npm install
npm run authorize

npm run authorize prints a URL — open it, sign in with the same Google account you added as a test user in step 3, and approve. The script catches the redirect on a local port automatically, saves a token to ~/.gsc-mcp-server/token.json, and exits. One-time step — the saved token is reused after this.

Step 7 — test it before involving Claude at all

npm run inspect

This opens Anthropic's own official MCP Inspector in a browser — a tool built specifically for testing MCP servers directly, call by call, before wiring them into a real client. Try list_sites first; if it returns your properties, the Google side of this is fully working and anything that goes wrong afterward is specific to Claude Desktop, not the server itself.

Step 8 — install it into Claude Desktop

Current Claude Desktop versions install local MCP servers as a packaged .mcpb file — Anthropic's own "MCP Bundle" format — through Settings → Extensions. This is not the same place as Settings → Connectors, which is for remote/HTTPS servers and won't show a local one.

Download the pre-built bundle directly — no build step needed: releases/gsc-mcp-server-v0.1.0.mcpb, click "Download raw file."

Use this install method — it's the one that actually worked in testing:

1. Open Claude Desktop → Settings → Extensions
2. Find Advanced settings → Install Extension…
3. Browse to the downloaded .mcpb file and select it

Double-clicking the file and dragging it into the Claude Desktop window are both also documented as valid install methods — neither worked reliably here: double-click did nothing at all on Windows, and dragging the file in got treated as a chat attachment instead of an install action. The Settings menu path above didn't have either problem.

Claude Desktop shows a permissions screen — review it, approve, and the four tools become available. One more thing worth knowing: once installed, it's actually listed under Settings → Connectors → Yours alongside any remote connectors — that's where to check it's there and enabled, even though the install itself happened through Extensions.

Step 9 — try it

Start a new chat and ask:

Claude Desktop will ask you to approve the tool call the first time — allow it. You should get back your verified properties. From there, something more useful:

Every real mistake made getting here

This is the part a polished walkthrough usually edits out. Each of these cost real troubleshooting time, and every one of them is now baked into the steps above so nobody else has to hit it blind.

A note on trusting this (or anything like it)

The honest version of "is this safe": this server can only do what its webmasters.readonly OAuth scope allows — read, never write — and it runs entirely on your own machine once installed, talking directly to Google's API with your own credentials. Nobody else's server sits in between. That said, "safe" for a downloaded binary isn't a property of the file format — it's a property of whether the source behind it is actually inspectable, which is why this is published as open source rather than a closed download, and why the bundle was verified by hand (not just assumed) before being written up here.

Documented vs. inferred vs. unsupported