search-console-mcp

Superfast, stdio-first MCP server for Google Search Console with:

• Fast startup
• Typed tool inputs
• In-memory TTL caching + request coalescing
• OAuth 2.0 refresh-token authentication

Features

Available MCP tools:

1. list_sites
2. query_performance
3. inspect_url
4. list_sitemaps
5. get_sitemap

Requirements

• Node.js 20+
• pnpm 9+
• Google Search Console property access
• OAuth client credentials + refresh token

Quick Start (Plug & Play)

1. Get your refresh token (one-time setup):

pnpm install
pnpm auth

This will:

• Prompt for your Client ID and Secret
• Open your browser for authorization
• Save credentials to .env automatically

2. Build and run:

pnpm build
pnpm start

That's it! The server reads credentials from .env automatically.

Getting Credentials

Step 1: Create OAuth Client ID on Google Cloud Console

1. Go to Google Cloud Console
2. Create a new project (or use an existing one)
3. Enable the Google Search Console API:
   • Navigate to "APIs & Services" → "Library"
   • Search for "Google Search Console API"
   • Click "Enable"
4. Create OAuth 2.0 credentials:
   • Go to "APIs & Services" → "Credentials"
   • Click "Create Credentials" → "OAuth client ID"
   • Choose "Desktop application" or "Web application"
   • Add redirect URI: http://localhost:9876 (unique port to avoid conflicts)
   • Copy the Client ID and Client Secret

Step 2: Get Refresh Token

Easiest way — use the built-in script:

pnpm install
pnpm auth

This will:

1. Prompt for Client ID and Secret
2. Open your browser for authorization
3. Automatically save to .env

Manual alternative if needed — use Google's OAuth 2.0 Playground:

1. Configure the OAuth Client ID (gear icon)
2. Use scope: https://www.googleapis.com/auth/webmasters
3. Authorize and copy the refresh token

Step 3: Find Your Search Console Site URL

1. Go to Google Search Console
2. Select your property
3. In the URL bar, you'll see a property like:
   • sc-domain:example.com (domain property)
   • https://example.com (URL prefix property)
4. Copy this value as your GSC_SITE_URL

Setup

After pnpm auth creates your .env, you're ready to go:

pnpm build
pnpm start

The server automatically reads GSC_CLIENT_ID, GSC_CLIENT_SECRET, GSC_REFRESH_TOKEN, and GSC_SITE_URL from .env.

Manual .env Setup (optional)

If you prefer to create .env manually:

cat > .env << 'EOF'
GSC_CLIENT_ID="your-client-id"
GSC_CLIENT_SECRET="your-client-secret"
GSC_REFRESH_TOKEN="your-refresh-token"
GSC_SITE_URL="sc-domain:example.com"
GSC_CACHE_TTL_MS="30000"
GSC_HTTP_TIMEOUT_MS="12000"
GSC_HTTP_RETRIES="2"
EOF

Then run:

pnpm build
pnpm start

Docker

Build image:

docker build -t search-console-mcp .

Run with .env file (easiest):

docker run --rm -i --env-file .env search-console-mcp

Or pass env vars directly:

docker run --rm -i \
	-e GSC_CLIENT_ID="your-client-id" \
	-e GSC_CLIENT_SECRET="your-client-secret" \
	-e GSC_REFRESH_TOKEN="your-refresh-token" \
	-e GSC_SITE_URL="sc-domain:example.com" \
	search-console-mcp

AI Agent Integration

Claude Desktop

Option 1: Docker via local MCP config (Recommended)

This is the most reliable Claude Desktop setup: no custom connector UI, no remote URL, no TLS hassle.

1. Build image:

docker build -t search-console-mcp .

2. Add this to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
	"mcpServers": {
		"search-console": {
			"command": "docker",
			"args": [
				"run",
				"--rm",
				"-i",
				"--env-file",
				"/absolute/path/search-console-mcp/.env",
				"search-console-mcp"
			]
		}
	}
}

Example absolute path:

/Users/devbyray/Projects/devbyrayray/search-console-mcp/.env

3. Restart Claude Desktop.

Option 2: Local Node.js process (stdio)

{
	"mcpServers": {
		"search-console": {
			"command": "bash",
			"args": ["-c", "cd /absolute/path/search-console-mcp && source .env && pnpm start"]
		}
	}
}

Option 3: Custom Connector UI (remote MCP URL)

Use this only when you have a real remote endpoint.

• URL must be https://.../mcp
• Certificate must be trusted by Claude (public CA certificate)
• localhost + self-signed certificates may fail in Custom Connector mode

For local development, prefer Option 1 or 2.

Claude Code (VS Code Extension)

Create .env.local in your project, then add to VS Code settings:

{
	"claude.mcpServers": {
		"search-console": {
			"command": "bash",
			"args": ["-c", "cd /absolute/path/search-console-mcp && source .env && node dist/index.js"]
		}
	}
}

GitHub Copilot

Best approach: Use .env with the server:

source .env && pnpm start

Then configure Copilot CLI to connect to the running server.

Docker Integration for AI Agents

For containerized deployments, use .env:

docker build -t search-console-mcp .
docker run --rm -i --env-file .env search-console-mcp

Other MCP Clients

All MCP clients can read .env files. Example configuration structure:

{
	"command": "bash",
	"args": ["-c", "cd /path/to/search-console-mcp && source .env && node dist/index.js"]
}

Or pass env vars directly from your .env file to the client configuration.

MCP Client Configuration Example

Generic reference (use .env for actual values):

{
	"mcpServers": {
		"search-console": {
			"command": "node",
			"args": ["/absolute/path/search-console-mcp/dist/index.js"],
			"env": {
				"GSC_CLIENT_ID": "your-client-id",
				"GSC_CLIENT_SECRET": "your-client-secret",
				"GSC_REFRESH_TOKEN": "your-refresh-token",
				"GSC_SITE_URL": "sc-domain:example.com"
			}
		}
	}
}

OAuth Refresh Token Notes

Use any OAuth 2.0 flow that produces a Google refresh token for the same client ID/secret pair. The server only needs the refresh token and will rotate access tokens automatically.

Development

pnpm dev

Tests:

pnpm test

Lint:

pnpm lint

Troubleshooting

• Missing required environment variable: check all required GSC_* vars.
• token_refresh_failed: verify OAuth client ID/secret and refresh token pair.
• google_api_error with 403: verify account access to the requested property.
• 429/5xx: retries are automatic; reduce request volume or increase interval between calls.