GSC MCP Server

A Model Context Protocol server that gives Claude (and any MCP client) read-only access to your Google Search Console data. Ask Claude about your SEO performance, rankings, click-through rates, and indexing status — all from natural conversation.

What You Get

9 tools that cover the full range of GSC data analysis:

Tool	What it does
gsc_query_performance	Flexible raw queries with full filter control — dimensions, date ranges, device, country
gsc_top_pages	Top performing pages ranked by clicks, impressions, CTR, or position
gsc_top_queries	Top search queries driving traffic to your site
gsc_page_queries	"What queries does this page rank for?"
gsc_query_pages	"Which pages rank for this query?" — cannibalization detection
gsc_position_tracker	Compare two date ranges to find ranking changes — flags significant movers
gsc_ctr_analysis	Quick wins: pages with high impressions but low CTR (title/meta optimization targets)
gsc_list_sites	List all GSC properties your account can access
gsc_inspect_url	Check index status, crawl info, mobile usability, and rich results for any URL

All tools support response_format: "markdown" | "json" and a site_url parameter for multi-site use.

Example Usage

Once configured, just ask Claude things like:

• "What are my top search queries this month?"
• "What is alloypartners.com/blog/venture-builder ranking for?"
• "Find pages with high impressions but low CTR — where can I improve titles?"
• "Which of my pages rank for 'venture studio'? Is there cannibalization?"
• "How have my rankings changed compared to last month?"
• "Is this URL indexed by Google?"

Quick Start

1. Clone and build

git clone https://github.com/drewbeechler/gsc-mcp-server.git
cd gsc-mcp-server
npm install
npm run build

2. Set up Google Cloud credentials (one-time)

You need OAuth 2.0 credentials to authenticate with the Search Console API. See Google Cloud Setup below for the full walkthrough.

3. Add to Claude

Claude Code — add to ~/.claude.json:

{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/path/to/gsc-mcp-server/dist/index.js"],
      "env": {
        "GSC_OAUTH_SECRETS_FILE": "/path/to/client_secrets.json",
        "GSC_SITE_URL": "sc-domain:yoursite.com"
      }
    }
  }
}

Claude Desktop — add the same config to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

4. Authorize

The first time a GSC tool is called, your browser will open for Google OAuth authorization. Sign in, approve, and the token is cached at ~/.gsc-mcp/token.json for all future sessions.

---

Google Cloud Setup

One-time setup to get OAuth credentials. Takes about 5 minutes.

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click the project dropdown at the top → New Project
3. Name it something like gsc-mcp-server → click Create
4. Make sure the new project is selected

Step 2: Enable the Search Console API

1. Go to APIs & Services → Library
2. Search for "Google Search Console API"
3. Click on it → click Enable

Step 3: Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen (may show as "Google Auth Platform")
2. Fill in App name (e.g., GSC MCP Server) and your email
3. For Audience/User type, select External (or Internal if you're on Google Workspace)
4. Add your email as a test user if prompted
5. Complete the setup

Note: The scopes are requested at runtime by the server — you don't need to manually add them in the console.

Step 4: Create OAuth Credentials

1. Go to APIs & Services → Credentials (or Clients in the new Auth Platform UI)
2. Click + Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Click Create → Download JSON
5. Save the file somewhere safe:

   mkdir -p ~/.gsc-mcp
   mv ~/Downloads/client_secret_*.json ~/.gsc-mcp/client_secrets.json
   

Step 5: Test it

npx @modelcontextprotocol/inspector node dist/index.js

This opens an interactive UI where you can test any tool. Try gsc_list_sites first to verify auth works.

"Unverified app" warning: If you set user type to External, you'll see this on first auth. Click Advanced → Go to GSC MCP Server (unsafe). This is normal for personal-use OAuth apps.

---

Environment Variables

Variable	Required	Description
GSC_OAUTH_SECRETS_FILE	Yes	Path to your client_secrets.json from Google Cloud
GSC_SITE_URL	No	Default GSC property (e.g., sc-domain:example.com). Can also be passed per-tool call.

You can set these in a .env file in the project root — the server loads it automatically via dotenv.

---

Troubleshooting

"Authentication failed (401)" — Delete ~/.gsc-mcp/token.json and restart to re-authorize.

"Site not found (404)" — Check the site_url format. Domain properties use sc-domain:example.com, URL-prefix properties use the full URL like https://example.com/.

"Access denied (403)" — Make sure your Google account has access to the Search Console property. Verify at search.google.com/search-console.

"No data returned" — GSC data lags 2-3 days. Default date ranges account for this, but if you've overridden dates to include today, that's likely the issue.

---

Tech Stack

• TypeScript + Node.js
• MCP SDK (@modelcontextprotocol/sdk) — stdio transport
• Google APIs (googleapis) — handles OAuth + token refresh natively
• Zod — runtime input validation

License

MIT