Content
# mcp-google-gsc
MCP server for Google Search Console -- search analytics, URL inspection, and site management via Claude.
## Features
- **Search Analytics** -- Query clicks, impressions, CTR, and position with flexible dimension filters (query, page, device, country, date)
- **URL Inspection** -- Check indexing status, mobile usability, and rich results for any URL
- **Site Listing** -- List all verified Search Console properties accessible to your authenticated account (OAuth user or service account)
- **Multi-Client Support** -- Manage multiple GSC properties with per-directory config mapping
## Installation
### From npm
```bash
npm install mcp-google-gsc
```
### From source
```bash
git clone https://github.com/mharnett/mcp-search-console.git
cd mcp-google-gsc
npm install
npm run build
```
## Configuration
**Security:** Never share your `.mcp.json` file or commit it to git -- it may contain API credentials. Add `.mcp.json` to your `.gitignore`.
mcp-gsc supports **two authentication modes**. Pick whichever fits your setup. Neither requires any file living at a hardcoded machine-local path -- credentials come from environment variables (or a `config.json` you create).
**Which mode to use:**
- **Service Account (Mode B) -- recommended for unattended / server / headless use.** A service account has no interactive login to expire or re-consent, so it is the right fit for always-on deployments. The one setup requirement is that the service account's email must be **granted access on each Search Console property** you want to query (see Mode B).
- **User OAuth (Mode A) -- for personal / interactive use**, where you want to authorize with your own Google login.
**Precedence when both are configured:** if a service-account keyfile is explicitly set (`GOOGLE_APPLICATION_CREDENTIALS`, or `credentials_file` in `config.json`), it **wins** over any OAuth refresh token or stored OAuth credentials. If neither is configured, the server fails loudly at startup with an onboarding message rather than silently guessing -- there is no machine-local default and no silent runtime failover between modes.
### Mode A: User OAuth (bring your own Google account)
Use this if you want to authorize with your own Google login (the account that has Search Console access). Best for personal / interactive use.
1. In the Google Cloud Console, create an **OAuth 2.0 Client ID** of type **Desktop app** and enable the **Search Console API**. (For a Desktop-app client, Google accepts any `http://localhost` loopback redirect -- you do not need to pre-register a port.)
2. Export your client credentials:
```bash
export GOOGLE_GSC_CLIENT_ID=...apps.googleusercontent.com
export GOOGLE_GSC_CLIENT_SECRET=...
```
3. Mint a refresh token (opens your browser, uses PKCE + `access_type=offline`):
```bash
node get-refresh-token.cjs
```
> Do **not** redirect this command's stdout to a shared log -- it prints the refresh token to stdout by design.
4. Copy the printed line into your environment:
```bash
export GOOGLE_GSC_REFRESH_TOKEN=...
```
The server reads `GOOGLE_GSC_CLIENT_ID`, `GOOGLE_GSC_CLIENT_SECRET`, and `GOOGLE_GSC_REFRESH_TOKEN` from the environment at runtime.
Alternatively, run the guided helper `npx mcp-gsc-auth`, which performs the same PKCE OAuth flow, lets you pick a default Search Console property, and writes the result to a per-user credentials file.
### Mode B: Service Account (recommended for unattended / server use)
Use this for server / headless / always-on contexts -- it is the recommended path when no human is present to complete or refresh an interactive login.
1. Create a Google Cloud **service account** with Search Console API access and download its JSON key file.
2. **Grant the service account's email access on each Search Console property** you want to query (add it as a user in Search Console). Without this grant on the property, the service account can authenticate but will see no sites.
3. Point the server at the key file **via an environment variable** (no hardcoded path):
```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json
```
### OAuth scope
Both modes request a single, **read-only** scope: `https://www.googleapis.com/auth/webmasters.readonly`. All four tools are reads -- nothing writes -- so the server never asks for read/write access.
The scope is defined once in `config.json` under `oauth.scope` (see `config.example.json`). The OAuth helper and the runtime read the same value, so they never drift. If `config.json` is absent (e.g. a fresh install), the committed read-only default is used.
### Multi-client config (optional)
To map working directories to Search Console properties, create a `config.json` in the project root (see `config.example.json`):
```json
{
"oauth": {
"scope": "https://www.googleapis.com/auth/webmasters.readonly"
},
"clients": {
"my-project": {
"name": "My Project",
"folder": "/path/to/project",
"site_url": "https://example.com/"
}
}
}
```
## Usage
Add to your Claude Code `.mcp.json`:
```json
{
"mcpServers": {
"gsc": {
"command": "node",
"args": ["/path/to/mcp-gsc/dist/index.js"]
}
}
}
```
Or if installed globally:
```json
{
"mcpServers": {
"gsc": {
"command": "npx",
"args": ["mcp-google-gsc"]
}
}
}
```
**Claude Desktop:** Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
## Tools
| Tool | Description |
|------|-------------|
| `gsc_get_client_context` | Detect the GSC property from your working directory based on config mapping |
| `gsc_list_sites` | List all verified Search Console properties accessible to the authenticated account |
| `gsc_search_analytics` | Query search performance data (clicks, impressions, CTR, position) with dimension and filter support |
| `gsc_inspection` | Inspect a URL for indexing status, mobile usability, and rich results |
### gsc_search_analytics
Supports dimensions: `query`, `page`, `device`, `country`, `date`. Filter by any dimension with operators like `equals`, `contains`, `notContains`. Date range defaults to the last 28 days.
### gsc_inspection
Returns index coverage, crawl status, mobile usability verdict, and rich result details for a specific URL within a property.
## Architecture
- **Resilience** -- Uses cockatiel for retry with exponential backoff and circuit breaker patterns on all Google API calls
- **Logging** -- Structured logging via pino with configurable log levels
- **Response Handling** -- Responses truncated at 200KB to stay within MCP transport limits
## License
MIT -- see [LICENSE](LICENSE).
---
Built by Mark Harnett / [drak-marketing](https://github.com/drak-marketing)
