Google Search Console MCP server

Connect Claude Desktop, Claude Code or any other MCP client to Google Search Console and use your real search data to improve the SEO of your websites and landing pages.

Ask things like:

• "Which of my landing pages could get the most extra traffic, and what should I change?"

• "Rewrite the title and meta description for /pricing based on the queries it ranks for."

• "Why did organic traffic drop last month?"

• "Are all the URLs in my sitemap indexed?"

• "Which pages are competing with each other for the same keywords?"

It runs locally on your machine over stdio. Your Google credentials are stored on your computer and only sent to Google.

What it can do

It also ships three prompts (slash commands in Claude Code, the "+" menu in Claude Desktop): seo_audit, optimize_page and investigate_traffic_drop.

Tools accept a property in any form: sc-domain:example.com, https://www.example.com/, or just example.com. Dates are Pacific Time like Search Console itself, and the default period is the last 28 days of final data.

Related MCP server: mcp-server-google-search-console

Setup

You need a Google account with access to at least one Search Console property, and Node.js 20 or later.

1. Create a Google OAuth client (one time, about 5 minutes)

Google requires every app that reads Search Console data to have its own OAuth client. You create one in your own Google Cloud project, so no third party ever sees your data or tokens.

1. Open the Google Cloud Console and create a project (or pick an existing one), for example "Search Console MCP".

2. Enable the Google Search Console API: APIs & Services > Library > Google Search Console API > Enable.

3. Configure the consent screen under Google Auth Platform: pick External as the audience (or Internal if you use Google Workspace and only need your organization's accounts), give it a name and your email.

4. Under Audience, click Publish app so it is "In production". In "Testing" mode Google expires your sign-in every 7 days. Since this app is only for you, you do not need Google's verification; you will see a "Google hasn't verified this app" screen when signing in, where you click Advanced > Go to (your app name).

5. Under Clients, click Create client, choose Desktop app, and Download JSON.

2. Sign in

npx @portside-labs/gsc-mcp auth --client-secret-file ~/Downloads/client_secret_XXXX.apps.googleusercontent.com.json

Your browser opens for Google sign-in. Afterwards the command prints the properties you can access. Credentials are saved to ~/.config/gsc-mcp/credentials.json (%APPDATA%\gsc-mcp on Windows) with owner-only permissions.

By default the server gets read-only access. To let it submit and delete sitemaps, add --write.

3. Add it to Claude

Claude Code

claude mcp add gsc --scope user -- npx -y @portside-labs/gsc-mcp

Claude Desktop

Open Settings > Developer > Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@portside-labs/gsc-mcp"]
    }
  }
}

Restart Claude Desktop. If it cannot find npx (common with nvm), use the full path from which npx as the command.

Alternatively, download the .mcpb bundle from the latest release and double-click it to install. Enter your OAuth client ID and secret in the settings dialog, then ask Claude to "sign in to Search Console".

Other MCP clients (Cursor, VS Code, Windsurf and so on): run npx -y @portside-labs/gsc-mcp as a stdio server.

Signing in from inside Claude

If you would rather not use a terminal, give the server your OAuth client through its environment and ask Claude to sign in. The login tool opens your browser and finishes the sign-in on its own:

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@portside-labs/gsc-mcp"],
      "env": {
        "GSC_OAUTH_CLIENT_ID": "1234-abc.apps.googleusercontent.com",
        "GSC_OAUTH_CLIENT_SECRET": "GOCSPX-..."
      }
    }
  }
}

Using a service account instead

Useful for automation, or for properties you do not own personally:

1. In Google Cloud, create a service account and a JSON key, and enable the Search Console API in that project.

2. In Search Console > Settings > Users and permissions, add the service account's email (...@....iam.gserviceaccount.com) as a user with Full or Restricted permission.

3. Set GSC_SERVICE_ACCOUNT_KEY_FILE=/path/to/key.json in the server's environment.

Application Default Credentials work too when you opt in with GSC_AUTH=adc (the server ignores GOOGLE_APPLICATION_CREDENTIALS otherwise, since it is often set for unrelated projects). With gcloud, sign in with the Search Console scope and set a quota project:

gcloud auth application-default login --scopes=https://www.googleapis.com/auth/webmasters,https://www.googleapis.com/auth/cloud-platform
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Configuration

CLI

npx @portside-labs/gsc-mcp           # start the MCP server (what Claude runs)
npx @portside-labs/gsc-mcp auth      # sign in (add --write for sitemap changes, --no-browser to print the URL)
npx @portside-labs/gsc-mcp status    # show the connected account and its properties
npx @portside-labs/gsc-mcp logout    # revoke and delete saved credentials

How the opportunity scoring works

• Expected CTR for each position comes from your own site: the median CTR of your queries at that rounded position. Positions with fewer than 8 queries of at least 20 impressions fall back to a conservative industry benchmark. Medians keep a few branded queries from distorting the curve. Every response shows the curve it used.

• Quick wins estimate impressions × expected CTR at the target position − current clicks.

• CTR opportunities flag rows whose CTR is below 70% of the expected CTR for their position, ranked by missed clicks.

• Exclude your brand with excludeQueryRegex (RE2 syntax, e.g. (?i)acme|acme corp) for cleaner results.

Search Console hides rare "anonymized" queries, so query-level numbers add up to less than the property totals. The analysis tools read up to 25,000 rows per breakdown (one API request), sorted by clicks; on bigger properties they say so in a note and you can narrow with pageRegex or queryRegex.

Privacy and security

• The server runs on your machine and talks only to Google's APIs and to the URLs you ask it to audit.

• OAuth uses PKCE and a one-time listener on 127.0.0.1. The refresh token is stored in a file only your user can read. logout revokes it with Google.

• audit_page, analyze_page and sitemap reading refuse localhost, private and link-local addresses (such as cloud metadata endpoints) unless you set GSC_MCP_ALLOW_PRIVATE_URLS=1. The check runs on the address actually connected to, on every redirect, so DNS rebinding cannot get around it.

• Page content fetched for audits is untrusted. The server returns extracted fields (title, headings and so on), not the raw page.

Troubleshooting

Development

npm install
npm run build        # compile to dist/
npm test             # unit and in-memory MCP integration tests
npm run typecheck
npm run pack:mcpb    # build the Claude Desktop bundle

Try a local build with the MCP Inspector: npx @modelcontextprotocol/inspector node dist/cli.js.

The tests run against an in-memory fake of the Search Console API (test/fakes.ts), so they need no Google account.

License

MIT © Portside Labs