Google Search Console MCP Server

An MCP (Model Context Protocol) server that provides comprehensive access to Google Search Console data for SEO analysis. Use it with Claude Code, Claude Desktop, or any MCP-compatible client.

Features

Site Management: List and inspect Search Console properties
Search Analytics: Query clicks, impressions, CTR, and position data
Multiple Dimensions: Analyze by query, page, country, device, or date
URL Inspection: Check index status, crawl info, and mobile usability
Sitemap Management: List and inspect submitted sitemaps
Period Comparison: Compare performance across date ranges for SEO reporting
Content Gap Analysis: Find query/page combinations to identify cannibalization

Available Tools

| Tool | Description | |------|-------------| | gsc_list_sites | List all accessible Search Console properties | | gsc_get_site | Get details about a specific site | | gsc_query_search_analytics | Flexible analytics query with dimensions/filters | | gsc_get_top_queries | Top search queries by clicks | | gsc_get_top_pages | Top pages by clicks | | gsc_get_performance_by_country | Geographic breakdown | | gsc_get_performance_by_device | Desktop/mobile/tablet metrics | | gsc_inspect_url | URL Inspection API - index status, crawl info | | gsc_list_sitemaps | List all sitemaps with submission status | | gsc_get_sitemap | Get specific sitemap details | | gsc_compare_periods | Compare performance between two date ranges | | gsc_get_query_page_combinations | Multi-dimension query for content gap analysis |

Prerequisites

Node.js 18+
A Google account with access to Search Console properties

Setup

1. Clone the Repository

git clone https://github.com/ksaitor/gsc-mcp.git
cd gsc-mcp

2. Install Dependencies

npm install

3. Build the Project

npm run build

4. Create Google OAuth Credentials

Go to Google Cloud Console - Credentials
Create a project (if you don't have one):
- Click the project dropdown at the top
- Click "New Project"
- Name it (e.g., "Search Console MCP")
- Click "Create"
Enable the Search Console API:
- Go to Search Console API
- Click "Enable"
Configure OAuth Consent Screen:
- Go to OAuth Consent Screen
- Select "External" (or "Internal" if using Google Workspace)
- Fill in the required fields (App name, User support email, Developer email)
- Click "Save and Continue"
- On "Scopes" page, click "Add or Remove Scopes"
- Search for and add: https://www.googleapis.com/auth/webmasters.readonly
- Click "Save and Continue"
- Add your email as a test user
- Click "Save and Continue"
Create OAuth Client ID:
- Go to Credentials
- Click "Create Credentials" → "OAuth client ID"
- Select "Desktop app" as application type
- Name it (e.g., "Search Console MCP")
- Click "Create"
- Click "Download JSON"
- Save the file as client_secret.json in this directory

5. Authenticate

Run the authentication script:

npm run auth

This will:

Open a browser window for Google authorization
Ask you to sign in and grant access to Search Console
Save credentials to credentials.json

You should see output like:

Success! Found 3 Search Console properties:
  - https://example.com/ (siteOwner)
  - sc-domain:example.com (siteOwner)

6. Configure MCP Client

Claude Code

Add to your Claude Code settings (~/.claude.json):

{
  "mcpServers": {
    "search-console": {
      "command": "node",
      "args": ["/path/to/gsc-mcp/dist/index.js"]
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "search-console": {
      "command": "node",
      "args": ["/path/to/gsc-mcp/dist/index.js"]
    }
  }
}

7. Restart Your MCP Client

Restart Claude Code or Claude Desktop to load the new MCP server.

Usage Examples

Once configured, you can ask Claude:

"List my Search Console properties"
"Show me the top 10 queries for example.com in the last 28 days"
"What are my top pages by clicks?"
"Compare last month's performance to this month for my site"
"Check if https://example.com/page is indexed"
"Show me performance by country for sc-domain:example.com"

Testing

Test the server with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

This opens a web UI where you can test all tools interactively.

Troubleshooting

"Request had insufficient authentication scopes"

Your credentials don't have the required Search Console scope. Re-run:

rm credentials.json
npm run auth

"Access blocked: This app's request is invalid"

Your OAuth consent screen may not be configured correctly:

Go to OAuth Consent Screen
Make sure you've added the webmasters.readonly scope
Add your email as a test user (if in testing mode)

"File not found: client_secret.json"

Download your OAuth credentials:

Go to Credentials
Find your OAuth 2.0 Client ID
Click the download button
Save as client_secret.json in this directory

"This site can't be reached" during auth

The auth script uses port 8080. If it's in use, you may need to modify src/auth.ts to use a different port.

Security Notes

Never commit credentials: Both client_secret.json and credentials.json are in .gitignore
Read-only access: This server only requests read access to Search Console data
Local credentials: All credentials are stored locally on your machine

Python Version

Looking for the Python version? Check out the python branch.

Acknowledgements

This project is based on the original Google Search Console MCP gist by @raoulalwani. Thanks for the foundation!

License

MIT

MCP Servers