Search Console MCP

An MCP server that connects Claude, Cursor and other AI assistants to Google Search Console.

It gives the assistant the raw data (search performance, URL inspection, sitemaps) and does the analysis on top: which keywords are one push from page one, which pages rank but are not clicked, which pages compete with each other, what lost traffic and why, and how much of your sitemap is indexed.

It runs on your machine, talks only to Google's API, and is read-only unless you switch writing on.

What you can ask

• "How did organic search do in the last 28 days compared with the month before?"
• "Which keywords are we close to ranking on page one for?"
• "Which pages rank in the top 10 but hardly get clicked? Suggest better titles."
• "Traffic dropped last week. What happened?"
• "Are any of our pages competing for the same keyword?"
• "Is https://example.com/pricing indexed? If not, why not?"
• "How much of our sitemap is indexed, and what is wrong with the rest?"
• "Pick the five blog posts most worth refreshing and write a brief for each."

What to use it for goes through each of these: what runs, what comes back and what to do with it.

Why this one

• It analyses, not only fetches. The opportunity tools return a ranked list of things to act on, with the numbers behind each.
• Estimates come from your own site. Expected click-through is measured on your data, not taken from a generic table.
• It says what the numbers do not show. Row caps, samples, hidden queries, incomplete days and empty comparison periods are stated in every result.
• Forgiving inputs. Say example.com or paste a page URL. Leave out the dates and you get the last 28 complete days.
• Read-only by default, with errors that tell you how to fix them and a doctor command that checks the setup.

Quick start

You need Node.js 22 or newer and a Google account with access to the Search Console properties you want to use.

1. Get Google credentials

Both ways are free. The authentication guide has every click.

Service account: in Google Cloud enable the Google Search Console API, create a service account, download a JSON key, then in Search Console add the service account's email under Settings > Users and permissions for each property.

Your own account: in Google Cloud enable the Google Search Console API, create an OAuth client of type Desktop app, download its JSON, then run:

GSC_OAUTH_CLIENT_FILE=/path/to/client_secret.json npx -y @pixfrix/search-console-mcp auth login

2. Add the server to your assistant

claude mcp add search-console \
  --env GSC_SERVICE_ACCOUNT_KEY=/path/to/service-account.json \
  -- npx -y @pixfrix/search-console-mcp

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@pixfrix/search-console-mcp"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY": "/path/to/service-account.json"
      }
    }
  }
}

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@pixfrix/search-console-mcp"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY": "/path/to/service-account.json"
      }
    }
  }
}

{
  "servers": {
    "search-console": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pixfrix/search-console-mcp"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY": "/path/to/service-account.json"
      }
    }
  }
}

On Windows, use forward slashes or doubled backslashes in JSON paths (C:/keys/gsc.json). If your client cannot start npx directly, use "command": "cmd" with "args": ["/c", "npx", "-y", "@pixfrix/search-console-mcp"].

3. Check that it works

GSC_SERVICE_ACCOUNT_KEY=/path/to/service-account.json npx -y @pixfrix/search-console-mcp doctor

[ ok ] Credentials: service account (seo-bot@my-project.iam.gserviceaccount.com)
[ ok ] Google sign-in
[ ok ] Search Console API
[ ok ] Properties (2):
         sc-domain:example.com  [siteFullUser]
         https://shop.example.com/  [siteRestrictedUser]

If a step fails, doctor says what to change. Then ask your assistant: "List my Search Console properties."

Documentation

Tools

Performance

Opportunities

Indexing and sitemaps

Prompts

Clients that support MCP prompts (Claude Desktop and Claude Code show them as slash commands) get six ready-made workflows:

Configuration

Everything is set through environment variables. Only credentials are required.

Credentials are looked up in this order: GSC_SERVICE_ACCOUNT_JSON, GSC_SERVICE_ACCOUNT_KEY, GOOGLE_APPLICATION_CREDENTIALS, a saved auth login, then Google's Application Default Credentials.

search-console-mcp                 Start the MCP server (what your client runs)
search-console-mcp doctor          Check credentials and list the properties you can read
search-console-mcp auth login      Sign in with your own Google account (--write for sitemap changes)
search-console-mcp auth logout     Forget the saved sign-in

Troubleshooting

Run doctor first: it tests credentials, sign-in, API access and property permissions in order and explains the first failure.

Privacy and security

• The server runs locally as a child process of your MCP client. It contacts googleapis.com, and your own site when audit_sitemap_indexing reads a sitemap. There is no telemetry.
• Credentials stay on your machine. A browser sign-in is stored as a refresh token in GSC_CONFIG_DIR. Delete it with auth logout.
• The default scope is read-only. Search data returned by the tools becomes part of your conversation with the AI assistant, under that assistant's own privacy terms.

See SECURITY.md to report a vulnerability.

Development

git clone https://github.com/PixFrixSystems/search-console-mcp.git
cd search-console-mcp
npm install
npm run build
npm test

The tests run against a stand-in for Google's API, so they need no credentials. With credentials, npm run live-check -- --site example.com runs every read-only tool against a real property and checks that the numbers agree with each other.

Contributions are welcome. See CONTRIBUTING.md.

License

MIT

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