mcp-gsc: a Google Search Console MCP server for SEOs who work inside Claude

The gap mcp-gsc fills between Search Console and an AI assistant

Search Console's own interface answers a fixed set of questions. If you want the queries that drove traffic to one page over a custom window, or a comparison of two arbitrary date ranges, you either export to a spreadsheet or write against the Search Console API yourself. mcp-gsc exists so that an MCP-compatible assistant can make those calls for you. The README frames it plainly: a Model Context Protocol server that connects GSC to AI assistants so you can analyze SEO data through natural language conversations.

The intended user is an SEO who already lives in a client that speaks MCP. The README lists Claude Desktop, Cursor, Codex CLI, Gemini CLI, and Antigravity. That is a narrower audience than anyone with a website, and deliberately so. If you do not already use one of those clients, the server has no interface of its own; there is no dashboard to open.

The repository also carries .claude-plugin/ and .cursor-plugin/ directories alongside skills/, which suggests the author ships client-specific integration files rather than relying only on a generic MCP config. The README itself does not document what those plugin directories contain, so treat them as a signal about intended clients, not as documented features.

How the server talks to Google and to your assistant

The architecture is a single Python module. pyproject.toml declares py-modules = ["gsc_server"], and the console entry points mcp-gsc and mcp-search-console both resolve to gsc_server:main. There is no package directory, no plugin registry, no database. The server is one file that registers MCP tools and forwards each one to the Google Search Console API.

Dependencies are the Google client stack plus the MCP SDK: google-api-python-client, google-auth-httplib2, google-auth-oauthlib, mcp[cli] with a version ceiling, and platformdirs. platformdirs is the piece that matters for state. It is the standard way to locate a per-user config or cache directory, which is where the OAuth token is persisted after the first browser sign-in. The README confirms this indirectly: after the first use, the token is saved and no browser interaction is needed again.

Transport defaults to stdio, which is how MCP subprocess servers normally run. The Dockerfile shows the alternative in a comment: override with MCP_TRANSPORT=sse for remote or network use. That is the only transport switch documented in the README, and it is an environment variable, not a flag.

The tool surface is broad rather than deep. Property management (list_properties, get_site_details), search analytics (get_search_analytics, get_performance_overview, compare_search_periods, get_search_by_page_query, get_advanced_search_analytics), URL inspection (inspect_url_enhanced, batch_url_inspection, check_indexing_issues), and sitemaps (get_sitemaps, list_sitemaps_enhanced, manage_sitemaps). get_capabilities and reauthenticate round it out. The README says the full list is 20 tools and tells you to ask the assistant to call get_capabilities.

Installing mcp-gsc with uvx and running a first query

The README recommends uvx over cloning, on the grounds that it needs no Python installation and no virtual environment. Install uv first. The README gives three commands and insists all three run in order, because the second activates the tool in the current shell and the third makes that permanent.

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
echo 'source $HOME/.local/bin/env' >> ~/.zshrc
uv --version

If uv --version prints a version, the toolchain is in place. Note that the third line appends to ~/.zshrc, so this assumes zsh. If your shell is bash, that line targets the wrong file and you will need to adapt it; the README does not cover that case.

Before any client configuration, you need Google credentials. Option A is an OAuth client ID of type Desktop app, created in Google Cloud Console after enabling the Search Console API, with the downloaded JSON saved somewhere permanent such as ~/Documents/client_secrets.json. Option B is a service account key saved as ~/Documents/service_account.json, with the service account email added to the GSC property under Settings, Users and permissions, Full access.

With credentials in place, the server runs as an MCP subprocess. The package name to point a client at is mcp-search-console, matching the project name in pyproject.toml. A minimal stdio configuration looks like this:

{
  "mcpServers": {
    "gsc": {
      "command": "uvx",
      "args": ["mcp-search-console"]
    }
  }
}

The repository ships a .mcp.json at the top level, which is the file to compare against if your client expects a different key layout. On first use, a browser window opens for Google sign-in. After that the token is cached. To confirm the server is alive and see what it can do, ask the assistant to call get_capabilities; the README describes that tool as returning the full tool list plus current auth status in one shot.

A reasonable first real task is a period comparison. Ask for compare_search_periods on your property with two date ranges. You supply the site URL and both ranges; the tool returns the performance delta. If auth is missing or expired, the release notes for 0.3.2 say all tools now tell you what to do, which is a small but real improvement over a silent failure.

Where mcp-gsc breaks, and when it is the wrong tool

The most instructive failure in the changelog is 0.3.3. The mcp SDK 2.0.0, released 2026-07-28, removed the mcp.server.fastmcp module. Every fresh uvx mcp-search-console install crashed on startup with ModuleNotFoundError: No module named 'mcp.server.fastmcp'. The fix was to pin mcp[cli]<2.0.0 in pyproject.toml and requirements.txt. That pin is still in place. It means the project is deliberately held below a major version of its own protocol SDK, and anyone who force-upgrades mcp past 2.0 will reproduce the crash. This is a dependency ceiling, not a bug that was eliminated.

OAuth is the second rough edge. Version 0.3.2 removed an isatty check that had blocked the browser login window from opening when the server ran as an MCP subprocess on macOS. Before that fix, uvx installs needed a manual terminal run to complete login. If you are on an older version, that workaround still applies.

Scope limits matter too. batch_url_inspection takes up to 10 URLs at once, per the tool table. If your audit covers thousands of URLs, this is the wrong instrument; you want a crawler that talks to the API directly. The server also has no scheduling. It answers when your assistant asks. There is no cron, no alerting, no stored history beyond whatever your MCP client keeps in the conversation.

Finally, the README's own banner promotes a hosted version with one-click sign-in and GA4 tools, limited to 100 seats. That is a commercial sibling, not part of this repository. It is worth knowing that the maintainer's attention is split, and that the hosted product is the one with GA4 coverage.

mcp-gsc against the raw Search Console API and hosted MCP servers

The honest alternative is not another MCP server. It is the Search Console API itself, called from a script. The difference is who writes the query. With google-api-python-client you build the request object, pick dimensions and filters, and handle pagination and quota yourself. You get exactly the fields you ask for and you can schedule the result. What you do not get is the conversational layer: no assistant deciding that a CTR drop on one page is worth checking with get_search_by_page_query next. mcp-gsc trades query precision for that back-and-forth.

A second alternative is the hosted Advanced GSC MCP that the README links. The trade is setup versus control. Hosted means one-click Google sign-in and no Google Cloud project to configure, plus GA4 tools that this repository does not have. Self-hosted means your OAuth client or service account is yours, the token lives in a local platformdirs directory, and nothing routes through a third party. For agencies handling client properties, that distinction usually decides the choice. The README also notes the hosted version is capped at 100 seats, so it is not an unconditional substitute.

Compared with writing your own MCP server, the value here is the 20 tool definitions and the auth plumbing, including the reauthenticate tool for switching accounts. That is maybe a day of work you do not repeat. The cost is inheriting the mcp SDK version ceiling and whatever the single gsc_server.py module does internally, since the README does not document its internals.

Maintenance, licensing and what upgrading costs you

The last push to the repository was on 2026-07-29. The project is not archived. Version 0.3.3 shipped in July 2026, and the changelog shows a steady cadence: 0.3.2 in April 2026, 0.3.3 in July 2026. pyproject.toml classifies the project as Development Status :: 4 - Beta, which is the author's own label and worth taking at face value.

Upgrade cost is concentrated in one place. Because mcp[cli] is pinned below 2.0.0, you cannot simply take the newest MCP SDK. When the SDK's breaking change is resolved upstream, the pin has to be lifted and the server retested. Until then, uvx installs resolve a working 1.x SDK, and the README explicitly says the --with "mcp<2" workaround is no longer needed. If you vendor this into a larger environment that pins mcp differently, that conflict is yours to resolve.

Licensing is MIT, declared in pyproject.toml with license-files = ["LICENSE"]. That is permissive: you can use, modify and redistribute it, including commercially, provided the licence text and copyright notice travel with it. The practical implication for agencies is that wrapping this server in an internal tool is unproblematic from a licensing standpoint. This is a description of the licence, not legal advice; if you are redistributing it inside a product, read the LICENSE file in the repository.

Requires-python is >=3.11, and the Dockerfile builds on python3.13-bookworm-slim via the uv image. If your environment is stuck on Python 3.10, this will not install.

Editorial conclusion

Adopt mcp-gsc if you already work in an MCP client, want your own Google credentials in the loop, and are comfortable creating an OAuth desktop client or a service account in Google Cloud Console. Skip it if you need a zero-setup hosted sign-in, or if you only want scheduled exports rather than conversational queries. Before adopting, verify that a fresh uvx mcp-search-console run resolves mcp[cli]<2.0.0, that your OAuth client is registered as a Desktop app, and that the service account email (if you use Option B) has been added under Users and permissions with Full access in the Search Console property.

Frequently asked questions

Official sources

1. AminForou/mcp-gsc on GitHub
2. Issues
3. License: MIT
4. README