MCP Google Search Console
Secure MCP server for Google Search Console analytics, sitemaps, and URL inspection
Open source Open in the app JSON README (API)
About
Secure MCP server for Google Search Console analytics, sitemaps, and URL inspection
Details
- Kind
- MCP servers
- Topic
- Web search, scraping & browser
- Publisher
- crunchtools
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Forks
- 1
- Last push
- 2026-09-06T02:35:38Z
- Repository state
- ativo
- Language
- Python
- License
- AGPL-3.0
- Added
- 2026-08-29 03:02:38
- Updated
- 2026-08-29 03:02:38
- Origin id
io.github.crunchtools/google-search-console
README
# mcp-google-search-console-crunchtools
<!-- mcp-name: io.github.crunchtools/google-search-console -->
Secure MCP server for Google Search Console. Query search analytics (clicks, impressions, CTR, position), manage sitemaps, inspect URL indexing status, and manage site properties.
[](https://github.com/crunchtools/mcp-google-search-console/actions/workflows/ci.yml)
[](https://pypi.org/project/mcp-google-search-console-crunchtools/)
[](https://www.gnu.org/licenses/agpl-3.0)
## Installation
### uvx (recommended, zero-install)
```bash
claude mcp add mcp-google-search-console-crunchtools \
--env GSC_CLIENT_ID=your_client_id \
--env GSC_CLIENT_SECRET=your_client_secret \
--env GSC_REFRESH_TOKEN=your_refresh_token \
-- uvx mcp-google-search-console-crunchtools
```
### pip
```bash
pip install mcp-google-search-console-crunchtools
```
### Container (Podman/Docker)
```bash
podman run -d -p 8017:8017 \
--env-file ~/.config/mcp-env/mcp-google-search-console.env \
quay.io/crunchtools/mcp-google-search-console \
--transport streamable-http --host 0.0.0.0
```
## OAuth Setup
This server supports two authentication methods: **browser-based OAuth** (recommended) and **environment variable** (fallback).
### Option A: Browser-Based OAuth (Recommended)
Browser-based OAuth handles token exchange automatically. When credentials expire, visit the `/auth` URL and click through Google's consent screen — no manual code exchange needed.
#### Step 1: Create a Google Cloud OAuth App
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project (or select an existing one)
3. Navigate to **APIs & Services > Library**
4. Search for **Google Search Console API** and click **Enable**
5. Navigate to **APIs & Services > Credentials**
6. Click **+ CREATE CREDENTIALS > OAuth client ID**
7. If prompted, configure the OAuth consent screen first:
- User type: **External** (or Internal if using Google Workspace)
- App name: anything (e.g., "MCP Search Console")
- Scopes: add `https://www.googleapis.com/auth/webmasters`
- Test users: add your Google account email
8. Back on Create OAuth client ID:
- Application type: **Web application**
- Name: anything (e.g., "MCP Search Console")
- Authorized redirect URIs: add your server's callback URL (e.g., `https://mcp-gsc.example.com/oauth2callback`)
9. Click **Create** — copy the **Client ID** and **Client Secret**
#### Step 2: Configure and Start
Create an env file:
```bash
cat > ~/.config/mcp-env/mcp-google-search-console.env << 'EOF'
GSC_CLIENT_ID=your_client_id
GSC_CLIENT_SECRET=your_client_secret
GSC_CREDENTIALS_DIR=/data
GSC_OAUTH_REDIRECT_URI=https://mcp-gsc.example.com/oauth2callback
EOF
chmod 600 ~/.config/mcp-env/mcp-google-search-console.env
```
Start the server with a persistent volume for credentials:
```bash
podman run -d -p 8017:8017 \
--env-file ~/.config/mcp-env/mcp-google-search-console.env \
-v mcp-gsc-data:/data:Z \
quay.io/crunchtools/mcp-google-search-console \
--transport streamable-http --host 0.0.0.0
```
#### Step 3: Authenticate
Visit `https://mcp-gsc.example.com/auth` in your browser. You'll be redirected to Google's consent screen. Grant access and the server will save credentials automatically.
When tokens expire, any tool call will return the `/auth` URL. Click it to re-authenticate — no container restart needed.
### Option B: Environment Variable (Fallback)
If you prefer static credentials or can't expose a callback URL, set `GSC_REFRESH_TOKEN` in your env file. See the [manual OAuth flow](#manual-oauth-flow) below.
<details>
<summary><strong>Manual OAuth flow</strong></summary>
```bash
export GSC_CLIENT_ID="your_client_id_here"
export GSC_CLIENT_SECRET="your_client_secret_here"
echo "https://accounts.google.com/o/oauth2/v2/auth?client_id=${GSC_CLIENT_ID}&redirect_uri=http://127.0.0.1&response_type=code&scope=https://www.googleapis.com/auth/webmasters&access_type=offline&prompt=consent"
```
1. Open the URL in your browser, sign in, and click **Allow**
2. Copy the `code=` value from the redirect URL
3. Exchange the code:
```bash
curl -s -X POST https://oauth2.googleapis.com/token \
-d "client_id=${GSC_CLIENT_ID}" \
-d "client_secret=${GSC_CLIENT_SECRET}" \
-d "code=PASTE_CODE_HERE" \
-d "grant_type=authorization_code" \
-d "redirect_uri=http://127.0.0.1" | python3 -m json.tool
```
4. Copy the `refresh_token` from the response and add `GSC_REFRESH_TOKEN=...` to your env file.
</details>
### How it works at runtime
The server checks for credentials in this order:
1. **File-based credentials** from `GSC_CREDENTIALS_DIR/credentials.json` (written by the browser-based flow)
2. **Environment variable** `GSC_REFRESH_TOKEN` (fallback)
On each API call, the server exchanges the refresh token for a short-lived access token (~1 hour), cached in memory and refreshed automatically. Updated tokens are persisted to the credentials file for reuse across container restarts.
## Available Tools (10)
| Category | Count | Tools |
|----------|------:|-------|
| Sites | 4 | list_sites, get_site, add_site, delete_site |
| Search Analytics | 1 | query_search_analytics |
| Sitemaps | 4 | list_sitemaps, get_sitemap, submit_sitemap, delete_sitemap |
| URL Inspection | 1 | inspect_url |
## Security
- OAuth2 credentials stored as `SecretStr` (never logged)
- File-based credentials written with `0o600` permissions (atomic writes)
- Automatic token scrubbing from error messages
- Pydantic input validation with `extra="forbid"`
- No filesystem access, shell execution, or code evaluation
- TLS certificate validation (httpx default)
- Request timeouts and response size limits
- Built on [Hummingbird](https://github.com/hummingbird-project) container images
See [SECURITY.md](SECURITY.md) for the full security design document.
## Development
```bash
uv sync --all-extras
uv run ruff check src tests
uv run mypy src
uv run pytest -v
gourmand --full .
podman build -f Containerfile .
```
## License
[AGPL-3.0-or-later](LICENSE)