AminForou/mcp-gsc: Google Search Console data in your AI assistant

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

Google Search Console has a web UI and an API. Neither is conversational. An SEO who wants to know which queries drove traffic to a specific page over the last 28 days either clicks through the interface or writes code against the Search Console API. mcp-gsc takes the second path and hides it behind the Model Context Protocol, so the request becomes a sentence in Claude Desktop, Cursor, Codex CLI, Gemini CLI or Antigravity.

The audience is narrow and specific: SEOs and developers who already live in an MCP-capable client and want GSC data in the same conversation as everything else. The README positions the project that way, listing the clients by name. If you do not use one of those clients, the server has nothing to talk to.

What it is not is a data warehouse or a reporting product. There is no scheduler, no alerting, no stored history. Each tool call hits the Search Console API and returns the result to the assistant. The value is the plumbing, not a new analytics engine.

How the server works: one Python module, twenty tools, Google's API underneath

The repository is deliberately small. gsc_server.py holds the server, pyproject.toml declares the dependencies, and the console scripts mcp-gsc and mcp-search-console both point at gsc_server:main. There is no service layer, no database, no cache. The Dockerfile copies the dependency files first for layer caching, syncs them, then copies gsc_server.py, which tells you the whole application is that one file.

Data flow is a straight line. The MCP client sends a tool call over stdio (or SSE, if MCP_TRANSPORT is set to sse). The server authenticates against Google using either an OAuth client secrets file or a service account JSON key, calls the Search Console API, and hands the structured result back to the assistant, which turns it into prose or a chart.

Authentication is the part that shapes everything else. In OAuth mode, the first run opens a browser window, the user signs in, and the token is saved so later runs are silent. In service account mode there is no browser at all; the service account email is added to the GSC property under Settings, Users and permissions, with Full access. That second path is what makes unattended or team setups possible, and it is also the one people get wrong, because a service account that has not been added as a property user will authenticate fine and then see nothing.

The tool surface is grouped by GSC concept: property management, search analytics, URL inspection, sitemaps. Some tools are thin (list_properties takes no arguments) and some are composite (check_indexing_issues takes a list of URLs and reports problems across them). get_capabilities exists purely so the assistant can discover what is available and whether auth is currently valid, which is a sensible answer to the common failure where a model does not know which tools it has.

Installing mcp-gsc with uvx and running a first query

Credentials come before installation. The README offers two routes. For OAuth, create a Google Cloud project, enable the Search Console API, create an OAuth client ID of type Desktop app, and download the JSON to a permanent path. For a service account, create the key, download the JSON, and add the service account email to the GSC property with Full access.

The recommended install path is uvx, which downloads and runs the server without cloning or managing a virtual environment. The README gives three commands in order, and the third makes the PATH change permanent for zsh sessions.

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

After that, uv --version should print a version. Then the server is registered with the MCP client. The repository ships .mcp.json and mcp.json at the top level, plus .claude-plugin/ and .cursor-plugin/ directories, so the client-specific wiring is largely a matter of pointing the client at the server entry rather than writing configuration from scratch.

The first real use is a discovery call rather than an analytics one. Ask the assistant to call get_capabilities. The release notes for 0.3.2 describe this tool as returning the full list of available tools plus current auth status in one shot, and it is the fastest way to confirm that credentials resolved. If auth is missing or expired, the same release added error messages that say what to do instead of failing silently.

Once auth is confirmed, a first analytics question is straightforward: ask for the top queries for a property over a period. That maps to get_search_analytics, which the README describes as returning top queries and pages with clicks, impressions, CTR and position. If the assistant returns an empty set for a property you know has traffic, the usual cause is that the OAuth account or service account is not a user on that property.

The dependency pin is the project's most important line

Version 0.3.3 exists because of a single upstream change. The mcp SDK 2.0.0, released 2026-07-28, removed the mcp.server.fastmcp module. Every fresh uvx mcp-search-console install crashed at startup with ModuleNotFoundError: No module named 'mcp.server.fastmcp'. The fix in 0.3.3 was to pin mcp[cli]<2.0.0, and pyproject.toml now carries mcp[cli]>=1.3.0,<2.0.0.

That is a real constraint, not a formality. The upper bound means the project cannot use the 2.x SDK until the server is ported off fastmcp. Anyone who resolves dependencies with the pin stripped out, or who vendors the server into an environment where mcp 2.x is already installed, will hit the same crash. The README notes that the pin removes the need for a --with "mcp<2" workaround, which tells you people were already working around it manually.

There is a second, quieter constraint. The Dockerfile defaults to stdio transport and says to override with MCP_TRANSPORT=sse for remote or network use. The README does not document what authentication looks like once the server is reachable over the network, which matters because an SSE endpoint that can read your Search Console data is a different security object from a local subprocess. Treat the Docker path as a starting point that needs its own review, not a turnkey remote deployment.

Python 3.11 or newer is required, per requires-python in pyproject.toml. The Dockerfile uses a python3.13 base image, so the container path is fine, but a local uvx run on an older interpreter will not resolve.

Where mcp-gsc stops being the right tool

The Search Console API returns at most the rows Google chooses to return per request, and the README does not describe pagination, aggregation or export behaviour for large properties. A site with hundreds of thousands of query-page combinations will not fit into a single tool response, and nothing in the documentation suggests the server stitches pages together. For bulk export work, the Search Console API's own bulk data export, or a warehouse pipeline, is the correct instrument.

The server also has no persistence. There is no place to store a baseline, so comparing this month to last month means passing two date ranges to compare_search_periods rather than querying stored history. If your workflow depends on alerting when a page drops out of the index, this is the wrong layer; you would need something that runs on a schedule and holds state.

batch_url_inspection is documented as accepting up to 10 URLs at once. That is a hard ceiling for the batch path, and URL inspection in general is subject to Google's own quota, which the README does not quantify. A migration with thousands of URLs to verify is not a job for this tool.

Finally, the repository is a single-file server with a test file, test_gsc_server.py, and no release artifacts retrieved. The README does not document a rollback procedure or a migration guide between versions. That is fine for a local developer tool and less fine if you plan to run it as shared infrastructure.

How it compares to calling the Search Console API directly

The honest alternative is not another MCP server. It is the google-api-python-client library that mcp-gsc already depends on. If you are comfortable writing Python, the Search Console API gives you the same data with no protocol layer, no dependency pin on an MCP SDK, and no assistant in the loop.

The difference is where the work goes. Direct API use means you write the query construction, the date handling, the pagination and the output formatting yourself, and you get exactly the shape you asked for. mcp-gsc means you accept its twenty tool signatures and its result formatting, and in exchange the assistant can decide which tool to call and can chain calls without you writing code. For an SEO who wants an answer in a chat window, that trade is favourable. For a data engineer building a recurring report, it is not.

A second alternative is the hosted server the README promotes under the Advanced GSC banner. It advertises one-click sign-in, GA4 tools, and support for Claude Desktop, Claude Code, Claude.ai, Codex and Cursor, with a stated limit of 100 seats. The trade is the usual one: no Google Cloud project to configure, but your Search Console data flows through someone else's service and the seat count is capped. The README does not state pricing or what happens after the seats are gone, so that decision has to be made on information outside this repository.

Licence, maintenance and what an upgrade costs you

The project is MIT licensed, declared in both pyproject.toml (license = "MIT", license-files = ["LICENSE"]) and the repository's LICENSE file. MIT is permissive: you can use, modify and redistribute it, including commercially, provided the copyright notice and licence text are preserved. That is a factual description of the licence, not legal advice; if you are embedding the server in a product, read the LICENSE file and take your own counsel.

The maintenance signal is the last push, on 2026-07-29, which is recent, and the repository is not archived. The changelog shows a steady cadence through 2026: 0.3.2 in April fixed the OAuth browser flow for uvx and added get_capabilities, 0.3.3 in July pinned the mcp SDK. Both releases were responses to concrete breakage rather than feature expansion, which is a reasonable sign for a wrapper this thin.

The upgrade cost is dominated by the dependency pin. Every time the mcp SDK moves, this project either follows or holds the upper bound. The 0.3.3 changelog is the evidence: a single upstream release broke every fresh install. If you deploy this, pin your own lockfile and read the changelog before bumping, because the failure mode is a startup crash, not degraded behaviour. The project classifiers still say Development Status :: 4 - Beta, which is worth taking at face value.

Editorial conclusion

Adopt it if you already have a Google Cloud project and want GSC queries, URL inspection and sitemap checks reachable from Claude Desktop, Cursor or Codex CLI without building the MCP layer yourself. Do not adopt it if you want a hosted service with one-click sign-in, or if you cannot create OAuth credentials and add a service account to a Search Console property. Verify first that the pinned mcp[cli]<2.0.0 resolves in your environment, that the OAuth browser window actually opens under your client, and that the 100-row Search Console API limit does not truncate the reports you care about.

Frequently asked questions

Official sources

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