Metadata-Version: 2.4
Name: mcp-google-search-console
Version: 2.0.0
Summary: MCP server for Google Search Console with automated SEO audit reports
Project-URL: Homepage, https://github.com/acamolese/google-search-console-mcp
Project-URL: Repository, https://github.com/acamolese/google-search-console-mcp
Project-URL: Issues, https://github.com/acamolese/google-search-console-mcp/issues
Author: Andrea Camolese
License-Expression: MIT
License-File: LICENSE
Keywords: audit,claude,google-search-console,mcp,seo
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.10
Requires-Dist: google-auth-oauthlib>=1.0.0
Requires-Dist: google-auth>=2.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# Google Search Console MCP

MCP (Model Context Protocol) server for **Google Search Console**. Query Search Console data and generate complete HTML SEO audit reports directly from any MCP-compatible client (Claude Code, Claude Desktop, Cursor, Zed, Continue, ...).

## Features

- **Read-only access** to Search Console (no write operations to your properties)
- **8 tools** covering sites, queries, pages, devices, countries, indexing, sitemaps, URL inspection
- **`gsc_audit`**: one-call generator for a self-contained HTML report with Chart.js graphs, automatic issue detection, concrete examples, actionable strategy and a 30/60/90-day roadmap
- **Brandable reports**: customize logo, font, colors via `branding.json`
- **Stateless-friendly**: credentials via environment variables, or XDG config dir

## Tools

| Tool | Description |
|---|---|
| `gsc_sites` | List all verified sites |
| `gsc_site_details` | Details of a specific site |
| `gsc_query` | Performance report with dimensions (query, page, country, device, date) |
| `gsc_performance_overview` | Aggregated metrics for a period (clicks, impressions, CTR, position) |
| `gsc_indexing_issues` | Check indexing status for a list of pages |
| `gsc_inspect_url` | Detailed URL Inspection for a single page |
| `gsc_sitemaps` | List all sitemaps submitted for a site |
| `gsc_audit` | Generate a complete HTML audit report for a date range |

## Installation

### Option A — `uvx` (recommended, zero setup)

Run directly from PyPI, no clone or venv required:

```bash
uvx mcp-google-search-console auth      # one-time OAuth authorization
uvx mcp-google-search-console            # start the MCP server
```

### Option B — `pipx`

```bash
pipx install mcp-google-search-console
mcp-google-search-console auth
mcp-google-search-console
```

### Option C — From source

```bash
git clone https://github.com/acamolese/google-search-console-mcp.git
cd google-search-console-mcp
uv venv && uv pip install -e .
.venv/bin/mcp-google-search-console auth
```

## Configuration

### 1. Google Cloud setup

1. [Google Cloud Console](https://console.cloud.google.com/) → create a project
2. Enable the **Google Search Console API**
3. **APIs & Credentials** → **Create Credentials** → **OAuth 2.0 Client ID** → **Desktop app**
4. Download the JSON

### 2. Provide the OAuth client credentials

You have three ways, pick whichever fits your setup. The server reads them in this order:

**A — Environment variables** (best for headless, CI, Docker, hosted MCP):

```bash
export GSC_CLIENT_ID="xxxxxxxxxxxx.apps.googleusercontent.com"
export GSC_CLIENT_SECRET="GOCSPX-xxxxxxxxxxxxxxxx"
export GSC_REFRESH_TOKEN="1//0xxxxxxxxxxxxxxxx"
```

With these three variables set, the server is fully stateless: no files are read or written.

**B — XDG config directory** (recommended for local desktop usage):

Save the OAuth client JSON as:

```
~/.config/mcp-google-search-console/oauth_credentials.json
```

Then run the interactive authorization flow:

```bash
mcp-google-search-console auth
```

This opens a browser, captures the OAuth consent and saves the refresh token to `~/.config/mcp-google-search-console/token.json`. On Linux and macOS the path honors `$XDG_CONFIG_HOME` if set.

**C — Legacy per-project directory** (backward compatibility only):

Place files under `./credentials/oauth_credentials.json` and `./credentials/token.json` in the working directory where the server is launched. This mode is still supported for older setups but not recommended.

## Client configuration

All examples below assume you installed with `uvx`. Adjust the command if you used `pipx` (`mcp-google-search-console`) or cloned from source (`/path/to/.venv/bin/mcp-google-search-console`).

### Claude Code

Edit `~/.claude/.mcp.json`:

```json
{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"]
    }
  }
}
```

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"]
    }
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json` (or the project-local `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"]
    }
  }
}
```

### Zed

Add to your Zed `settings.json` under `context_servers`:

```json
{
  "context_servers": {
    "google-search-console": {
      "command": {
        "path": "uvx",
        "args": ["mcp-google-search-console"]
      }
    }
  }
}
```

### Continue, Windsurf, and other MCP clients

Any MCP client that supports stdio servers can use the same pattern:

```json
{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"]
    }
  }
}
```

### Stateless configuration with environment variables

If you prefer not to persist anything on disk, pass credentials inline:

```json
{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"],
      "env": {
        "GSC_CLIENT_ID": "xxxxxxxxxxxx.apps.googleusercontent.com",
        "GSC_CLIENT_SECRET": "GOCSPX-xxxxxxxxxxxxxxxx",
        "GSC_REFRESH_TOKEN": "1//0xxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

## Usage examples

Once the MCP server is wired into your client, you can ask things like:

- "List my verified sites in Search Console"
- "Show the top 50 queries for `sc-domain:example.com` over the last 30 days"
- "Check if these 5 pages are indexed: ..."
- "Generate a complete audit of `example.com` for the period 2026-01-01 → 2026-03-31"

The `gsc_audit` tool writes a self-contained HTML file to `~/gsc-reports/` and returns the path. Open it in any browser.

### Tips

- Use `sc-domain:example.com` for domain properties or `https://example.com/` for URL-prefix properties.
- Available dimensions for `gsc_query`: `query`, `page`, `country`, `device`, `date` (combine with commas).
- Maximum 25,000 rows per request.

## Customizing the audit report

The audit report layout uses a Jinja2 template in `src/google_search_console_mcp/templates/report.html.j2` with colors and fonts driven by `branding.json`.

To customize without touching the package, create your own `branding.json` in the XDG config directory:

```
~/.config/mcp-google-search-console/branding.json
```

Example:

```json
{
  "brand_name": "Acme SEO Studio",
  "logo": "logo.png",
  "font_family": "Poppins",
  "font_url": "https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700&display=swap",
  "colors": {
    "primary": "#ff6b35",
    "primary_dark": "#cc4a1f",
    "secondary": "#004e89",
    "accent": "#00b894",
    "danger": "#e74c3c",
    "warning": "#f39c12",
    "text": "#004e89",
    "text_muted": "#5a6c7d",
    "text_light": "#8395a7",
    "bg": "#f8f9fc",
    "surface": "#ffffff",
    "border": "#e1e8ed"
  }
}
```

The `logo` field accepts either a local file name (resolved against the XDG config dir, then the package dir) or a full URL. Local files are automatically base64-encoded into the HTML so the report stays self-contained.

You can also pass a custom branding file per report via the `branding_path` parameter of `gsc_audit`:

> "Generate an audit of example.com using the branding at `/path/to/client-branding.json`"

## Security

- Never commit `oauth_credentials.json`, `token.json`, or `.env` files with real secrets.
- The XDG config directory is the default storage location and is outside the repository.
- The server only requests the `webmasters.readonly` scope.

## Troubleshooting

- **401 Unauthorized on first call**: token expired or missing. Run `mcp-google-search-console auth` or set `GSC_REFRESH_TOKEN`.
- **"No OAuth client credentials found"**: neither env vars nor files are configured. See the Configuration section.
- **Browser flow fails on headless machines**: skip `auth` entirely and export `GSC_CLIENT_ID`, `GSC_CLIENT_SECRET`, `GSC_REFRESH_TOKEN` as environment variables.

## License

MIT
