Content
# 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
```bash
git clone https://github.com/ksaitor/gsc-mcp.git
cd gsc-mcp
```
### 2. Install Dependencies
```bash
npm install
```
### 3. Build the Project
```bash
npm run build
```
### 4. Create Google OAuth Credentials
1. Go to [Google Cloud Console - Credentials](https://console.cloud.google.com/apis/credentials)
2. 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"
3. Enable the Search Console API:
- Go to [Search Console API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com)
- Click "Enable"
4. Configure OAuth Consent Screen:
- Go to [OAuth Consent Screen](https://console.cloud.google.com/apis/credentials/consent)
- 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"
5. Create OAuth Client ID:
- Go to [Credentials](https://console.cloud.google.com/apis/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:
```bash
npm run auth
```
This will:
1. Open a browser window for Google authorization
2. Ask you to sign in and grant access to Search Console
3. 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`):
```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):
```json
{
"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:
```bash
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:
```bash
rm credentials.json
npm run auth
```
### "Access blocked: This app's request is invalid"
Your OAuth consent screen may not be configured correctly:
1. Go to [OAuth Consent Screen](https://console.cloud.google.com/apis/credentials/consent)
2. Make sure you've added the `webmasters.readonly` scope
3. Add your email as a test user (if in testing mode)
### "File not found: client_secret.json"
Download your OAuth credentials:
1. Go to [Credentials](https://console.cloud.google.com/apis/credentials)
2. Find your OAuth 2.0 Client ID
3. Click the download button
4. 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](https://github.com/ksaitor/gsc-mcp/tree/python).
## Acknowledgements
This project is based on the original [Google Search Console MCP gist](https://gist.github.com/raoulalwani/bd22f1edd87cd111f890665631c6270d) by [@raoulalwani](https://github.com/raoulalwani). Thanks for the foundation!
## License
MIT
