Google Search Console MCP Server

A Model Context Protocol (MCP) server for Google Search Console — connect it to Claude Desktop, Claude Code, or any other MCP-compatible client and ask questions about your site's search analytics (clicks, impressions, CTR, position), sitemaps, and indexing status directly in chat.

What it can do

Related MCP server: mcp-gsc

Requirements

• Node.js 18+

• A Google account with Owner or Full user access to the site(s) in Google Search Console

1. Create a Google Cloud project and enable the API

1. Go to the Google Cloud Console and create a new project (top bar → project dropdown → New Project). Give it any name, e.g. GSC Connection.

   

2. With that project selected, open APIs & Services → Library, search "Google Search Console API", and click Enable.

Everything below branches by auth method — pick one.

2a. Option A — OAuth 2.0 (recommended if this is just for you)

Uses your own Google login, so it automatically sees every property you personally have access to. Requires a one-time browser authorization.

Configure the consent screen:

1. Go to APIs & Services → OAuth consent screen (in the newer Cloud Console this is under Google Auth Platform → Branding, part of a 4-step setup wizard).

2. App information: enter an app name (e.g. GSC MCP Server) and your email as the support email → Next.

   

3. Audience: choose External → Next.

4. Contact information: enter your email → Next.

5. Finish: accept the policy → Create.

6. On the Audience page that follows, scroll to Test users → Add users, and add your own Google account's email. While the app is unpublished ("Testing" status), only test users can complete the login — this is expected and fine to leave as-is indefinitely for personal use.

   

Create the OAuth client:

1. Go to Clients (left sidebar) → Create client.

2. Application type: Web application (not "Desktop" — this project's local auth flow expects a fixed redirect URI, which only the Web application type lets you set).

3. Name it anything, e.g. GSC MCP.

4. Under Authorized redirect URIs, click Add URI and enter exactly:

   http://localhost:53682/oauth2callback

   

5. Click Create, then download the client JSON (via the download icon next to the client in the Clients list).

6. Save the downloaded file into this project's folder as oauth-credentials.json.

   

Configure and authorize:

7. Copy .env.example to .env and set (use absolute paths — see the note below):

   GSC_OAUTH_CREDENTIALS_PATH=/absolute/path/to/google-search-console-mcp-server/oauth-credentials.json
   GSC_OAUTH_TOKEN_PATH=/absolute/path/to/google-search-console-mcp-server/.gsc-token.json

8. Run the one-time login:

   npm run auth

   This prints a URL — open it in your browser, log in with the account you added as a test user, and approve access. The CLI saves a token to .gsc-token.json and you're done; you won't need to repeat this unless the token is deleted or access is revoked.

Why absolute paths? .env paths are resolved relative to the current working directory of whatever process launches the server — that's your shell when you run npm run dev, but it's a different, unpredictable directory when an app like Claude Desktop spawns the server for you. Relative paths (./oauth-credentials.json) can silently fail to resolve in that case, causing an unexplained "no credentials" error. Absolute paths always work regardless of who launches the process.

2b. Option B — Service account (no browser login, better for servers/CI)

1. In Cloud Console, go to APIs & Services → Credentials → Create Credentials → Service account.

2. Give it any name (e.g. gsc-mcp) and click Done (no project-level roles needed).

3. Open the new service account → Keys tab → Add Key → Create new key → JSON. Save the downloaded file into this project's folder, e.g. gsc-service-account.json.

4. Copy the service account's email address (looks like gsc-mcp@your-project.iam.gserviceaccount.com).

5. In Google Search Console, open the property → Settings → Users and permissions → Add user → add the service account's email as a Full user. Repeat for every property you want this server to see.

6. In .env (absolute path, same reasoning as above):

   GSC_SERVICE_ACCOUNT_KEY_PATH=/absolute/path/to/google-search-console-mcp-server/gsc-service-account.json

3. Install and build

git clone https://github.com/wyattxmgmt/google-search-console-mcp-server.git
cd google-search-console-mcp-server
npm install
npm run build

(You should already have .env set up from section 2a or 2b above.)

4. Connect it to an MCP client

Claude Desktop

The current Claude Desktop app manages local MCP servers under Settings → Developer → Local MCP servers, not under Settings → Connectors (Connectors there is for remote/hosted MCP servers reachable over HTTPS — a locally-run server like this one won't show up there).

1. Open Settings → Developer → Local MCP servers → Edit Config. This opens claude_desktop_config.json directly.

2. Add a mcpServers entry (merge with whatever's already in the file — don't replace it):

   {
     "mcpServers": {
       "gsc": {
         "command": "node",
         "args": [
           "--env-file=/absolute/path/to/google-search-console-mcp-server/.env",
           "/absolute/path/to/google-search-console-mcp-server/dist/index.js"
         ]
       }
     }
   }

3. Save, then fully quit Claude Desktop (not just close the window — use the tray/taskbar icon) and reopen it.

4. Check Settings → Developer → Local MCP servers again — gsc should show status running.

   

Claude Code

Copy .mcp.json.example to .mcp.json in this project and fill in the absolute path:

{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["--env-file=.env", "dist/index.js"],
      "cwd": "/absolute/path/to/google-search-console-mcp-server"
    }
  }
}

Open Claude Code in this directory — it'll prompt you to approve the project-scoped gsc server on first load. To make it available in every session regardless of directory, register it globally instead:

claude mcp add gsc --scope user -- node --env-file=/absolute/path/to/google-search-console-mcp-server/.env /absolute/path/to/google-search-console-mcp-server/dist/index.js

Any other MCP client

The server speaks standard MCP over stdio — point your client at node dist/index.js with the same environment variables set (or --env-file), and it will work the same way.

Example prompts once connected

• "List my Search Console properties"

• "What were my top 20 queries for example.com over the last 28 days?"

• "Compare clicks by device for example.com in July vs June"

• "Is https://example.com/some-page indexed? Run a URL inspection."

• "Submit https://example.com/sitemap.xml as a new sitemap"

Troubleshooting

• "No credentials configured" — you need exactly one of GSC_SERVICE_ACCOUNT_KEY_PATH or GSC_OAUTH_CREDENTIALS_PATH set in .env.

• "No cached OAuth token found" — run npm run auth first.

• Works with npm run dev but fails/times out when launched by Claude Desktop — almost always relative paths in .env. Switch to absolute paths (see the callout in 2a).

• Empty results from list_sites — the account/service-account tied to your credentials hasn't been added as a user on any property in Search Console.

• 403 errors on a specific site — double check the exact siteUrl format Search Console uses for that property (e.g. sc-domain:example.com for domain properties vs. https://example.com/ for URL-prefix properties) — see it via list_sites.

• Google shows "app isn't verified" / blocks login — expected while the OAuth consent screen is in "Testing" status. Make sure the Google account you're logging in with was added under Audience → Test users.

Development

npm run dev    # run directly with tsx, no build step
npm run build  # compile to dist/

License

MIT