ayhammouda/gsc-seo-mcp

**Secure, read-only Google Search Console access for AI agents, with exact
property allowlists and a hardened TypeScript MCP runtime.**
gsc-seo-mcp lets MCP-compatible clients query Google Search Console without
exposing a broad or write-capable API surface. It currently provides four
direct read tools over local stdio and fails closed unless an exact Search
Console property allowlist is configured.
If this project is useful to you, consider
starring it on GitHub and sharing
the use case you want it to support in
Discussions.
Why use it
- **Read-only by design:** the default and only contained runtime profile uses
Google's webmasters.readonly scope.
- **Exact property containment:** every request is checked against a required,
normalization-aware allowlist before Google is called.
- **Bounded execution:** inputs, outputs, concurrency, and Google request time
are capped to reduce accidental or adversarial resource use.
- **Agent-ready protocol:** Codex, Claude, Cursor, and other MCP clients can use
the same Zod-typed tool contracts over stdio.
> **Release freeze:** npm, MCP Registry, GitHub Release, and public MCPB
> publishing are technically blocked through WP-10 and until the freeze is
> explicitly lifted.
> An active GitHub ruleset blocks creation, movement, and deletion of v*
> tags; if that rule is deliberately disabled, the tag workflow still builds
> evidence and fails at the freeze gate. The current runtime surface is
> intentionally limited to stdio, four direct read tools, and an exact property
> allowlist.
Source-Only Setup
Do **not** install or execute the unscoped npm package gsc-seo-mcp: that registry name belongs to an unrelated publisher and is not this repository. WP-10/WP-11 must select and verify a collision-free package identity before npm or MCP Registry installation guidance returns.
Use the audited source checkout during containment:
Project MCP configuration
The repository includes a project-scoped .mcp.json for clients that support
checked-in MCP server configuration. It launches the built source checkout and
does not use the unrelated npm package:
Build first, then export GSC_SEO_MCP_ALLOWED_PROPERTIES as a JSON array of
the exact properties this checkout may access. The missing variable has no
fallback: project configuration must fail closed instead of silently widening
access.
Build the MCPB 0.1.0 candidate
The repository includes a manifest-format 0.4 MCP Bundle build. It packages the
compiled stdio server and production dependencies, validates the manifest with
the pinned official MCPB CLI, and writes a SHA-256 checksum:
Generated files are written to artifacts/ and remain local while the release
freeze is active. See MCPB packaging and authentication for the
bundle contents, checksum command, ADC prerequisite, and publication status.
Authentication
Two authentication modes are supported:
- stored (default): node dist/cli.js auth login manages a local token store using your OAuth client ID and secret.
- adc: use Google Application Default Credentials, such as credentials created by gcloud auth application-default login.
Stored OAuth Tokens
Create OAuth credentials in Google Cloud, enable the Search Console API, then set:
Login for read-only access:
Check credential presence without printing secrets:
Application Default Credentials
ADC mode avoids GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET at server launch time:
If gcloud requires a custom OAuth client for non-Cloud scopes, create a Desktop OAuth client in Google Cloud and pass its downloaded JSON:
By default, the server requests only:
The containment profile does not provide a write-capable login or runtime mode. operator, full_admin, unknown modes, and the legacy GSC_SEO_MCP_READONLY=false setting are rejected.