mcp-gsc: Google Search Console Data in Your AI Assistant via MCP

What mcp-gsc Solves and Who It Is For

Google Search Console exposes its data through an API, but most SEO practitioners interact with it through the web dashboard. Pulling search performance data, comparing periods, batch-inspecting URLs for indexing problems, and checking sitemap status all require either manual dashboard work or custom scripts against the API.

mcp-gsc exposes 20 GSC tools to any MCP-compatible AI assistant. Instead of navigating the dashboard or writing a Python script, a practitioner can type a natural-language question to their AI assistant and have it call the appropriate tool, format the results, and respond. The assistant can also create visualizations from the returned data, since it receives the raw numbers and can chart them.

The primary audience is SEOs, growth engineers, and web developers who use Claude Desktop, Cursor, Codex CLI, or Gemini CLI and spend meaningful time on GSC analysis.

Authentication: OAuth and Service Account

Two authentication methods are available. OAuth is the recommended path for individual use. It requires creating an OAuth client ID in Google Cloud Console, enabling the Search Console API, downloading the JSON credentials file, and providing its path to the mcp-gsc configuration. On first use, a browser window opens for Google account sign-in. After that, the token is saved and no further browser interaction is needed.

The service account path suits automation and team deployments. Create a service account in Google Cloud Console, generate a JSON key file, and add the service account email as a user in the Google Search Console property. Service accounts do not trigger browser-based OAuth flows, which makes them suitable for headless environments and scheduled runs.

A known issue documented in the changelog is that the OAuth browser flow previously failed when running as an MCP subprocess on macOS. This was fixed in version 0.3.2 by removing the isatty check that blocked the browser login window.

Installing mcp-gsc and Configuring an AI Client

The recommended installation method uses uvx, which runs the package without a persistent install:

uvx mcp-search-console

For Claude Desktop, Cursor, Codex CLI, and other MCP-compatible clients, configure the server in your client's MCP settings file, pointing it at the uvx command and passing the path to your OAuth credentials file as an environment variable. Each client has its own MCP configuration format; consult the client's documentation for the exact config structure.

For Docker-based deployments, a Dockerfile is included in the repository:

FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim
WORKDIR /app
COPY pyproject.toml README.md ./
RUN uv sync --no-cache --no-install-project
COPY gsc_server.py .
CMD ["uv", "run", "--no-sync", "python", "gsc_server.py"]

The Docker image defaults to stdio transport. Set MCP_TRANSPORT=sse in the environment to switch to SSE transport for remote or network use. This is the expected path for teams hosting the server as a persistent network service rather than launching it on demand from a local MCP client.

The 20 Available Tools

The server exposes tools across four areas: property management, search analytics, URL inspection, and sitemap management.

Property management tools include list_properties to see all GSC properties, get_site_details for a specific property, and reauthenticate to switch Google accounts.

Search analytics tools include get_search_analytics for top queries and pages with clicks, impressions, CTR, and position; get_performance_overview for a period summary; compare_search_periods to compare two date ranges; get_search_by_page_query for terms driving traffic to a specific page; and get_advanced_search_analytics with filters by country, device, query, and page.

URL inspection tools include inspect_url_enhanced for a single URL's crawl and index status including rich-result markup issues, batch_url_inspection for up to 10 URLs at once, and check_indexing_issues for identifying indexing problems across a set of URLs.

Sitemap tools include get_sitemaps, list_sitemaps_enhanced with error and warning details, and manage_sitemaps for submitting or deleting sitemaps.

The get_capabilities tool is available as a first call to list all available tools and check authentication status. The README recommends calling it when the AI assistant is uncertain about what is available.

Notable Bugs Fixed in Recent Releases

The 0.4.0 and 0.4.1 releases fixed several bugs that silently corrupted results in earlier versions.

In compare_search_periods, the period order was reversed: Period 1 was being treated as the baseline and Period 2 as the analyzed period, making growth appear as decline. This was corrected in 0.4.0 so that Period 1 is now the analyzed period and Period 2 the baseline.

In get_advanced_search_analytics, the sort_by and sort_direction parameters were accepted but silently ignored, returning unsorted results. This was fixed in 0.4.0.

In inspect_url_enhanced and batch_url_inspection, rich-result issues were being read from the wrong API response path, causing markup problems to be silently dropped rather than surfaced. Fixed in 0.4.0.

In check_indexing_issues and batch_url_inspection, requests against sc-domain: properties timed out when processing 10-URL batches because calls were sequential. Both were made concurrent in 0.4.0 and 0.4.1 respectively.

The 0.3.3 release fixed a startup crash for fresh installs caused by the mcp 2.0.0 SDK removing the mcp.server.fastmcp module. The project pins mcp[cli] below 2.0.0 to prevent this from recurring.

Limitations: What mcp-gsc Cannot Do

mcp-gsc has read-oriented capabilities for search analytics and read-write capabilities for sitemaps. It does not cover Google Analytics 4 data. The README links to an advanced hosted version at advancedgsc.com that adds GA4 tools and a one-click sign-in flow, but that version has a limited seat count and is a separate product. The open-source version in this repository handles only GSC data.

Batch URL inspection is limited to 10 URLs per call, which is the GSC API's limit for URL inspection. There is no documented workaround for inspecting larger sets in a single operation; the expected approach is to call the tool multiple times. The 0.4.1 release made batch_url_inspection and check_indexing_issues run concurrently within that 10-URL window, which resolved timeout issues on sc-domain: properties, but did not change the 10-URL cap.

The mcp SDK pin at below 2.0.0 is a meaningful constraint for teams who use other MCP tools that have already moved to the 2.0 SDK. The pin exists because 2.0.0 removed the fastmcp module this project depends on, and an SDK upgrade would require a refactor. Running mcp-gsc alongside tools that already use the 2.0 SDK may require virtualenv isolation or the Docker container to avoid version conflicts. A comparable tool for teams that need GA4 data alongside GSC data would need a separate MCP server.

Maintenance, Versioning, and License

The last push to the repository was on 2026-09-15. The current version is 0.4.1. The project is licensed under MIT. A detailed CHANGELOG.md tracks each release with specific bug fixes and contributor attribution, including the GitHub usernames of contributors who reported and fixed individual bugs.

The pyproject.toml defines the package as mcp-search-console and lists the entry points as both mcp-gsc and mcp-search-console, giving two equivalent command names. Python 3.11 or higher is required. The dependency list is minimal: google-api-python-client at 2.163.0 or higher, google-auth-httplib2, google-auth-oauthlib, mcp[cli] pinned below 2.0.0, and platformdirs. The platformdirs library is used to locate platform-appropriate storage paths for the saved OAuth token.

A .claude-plugin/ directory and a .cursor-plugin/ directory are present in the repository for IDE-specific MCP configurations, and a skills/ directory suggests the project also supports skill-based agent integrations for agent runtimes that support the SKILL.md format. A CLAUDE.md is also present, indicating the repository has agent-specific instructions configured.

Editorial conclusion

mcp-gsc is the right tool for an SEO practitioner or developer who already uses an MCP-compatible AI assistant and wants to query Google Search Console data conversationally without writing scripts or navigating the GSC dashboard for every check. The limitation to verify before installing is the dependency pin: mcp[cli] is pinned below 2.0.0 because the 2.0.0 SDK removed the fastmcp module that this project depends on. If your environment already uses the mcp 2.0 SDK for other tools, confirm that a lower version can coexist or use the Docker container to isolate it.

Frequently asked questions

Official sources

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