# GSC-MCP-Server
> Google Search Console MCP Server — Connect Google Search Console to Claude, Cursor, and other MCP clients.
[](https://www.npmjs.com/package/@appsyogi/gsc-mcp-server)
[](https://www.npmjs.com/package/@appsyogi/gsc-mcp-server)
[](https://opensource.org/licenses/MIT)
[](https://github.com/AppsYogi-com/gsc-mcp-server/actions/workflows/ci.yml)
## Features
- 🔍 **Search Analytics** — Query clicks, impressions, CTR, and position data
- 📊 **SEO Opportunities** — Find low-CTR keywords, detect cannibalization issues
- 📈 **Reports** — Weekly summaries, period comparisons
- 🗺️ **Sitemaps** — List, submit, and manage sitemaps
- 🔎 **URL Inspection** — Check indexing status (requires full scope)
- 💾 **Caching** — SQLite cache for faster repeated queries
- 🔐 **Secure** — OAuth tokens stored in OS keychain
## Quick Start
```bash
# Install globally
npm install -g @appsyogi/gsc-mcp-server
# Set up OAuth credentials
gsc-mcp init
# Verify setup
gsc-mcp doctor
# Start the server (for MCP clients)
gsc-mcp run
```
## Prerequisites
### 1. Create Google Cloud OAuth Credentials
You need to create your own OAuth credentials in Google Cloud Console:
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the **Google Search Console API**:
- Go to "APIs & Services" → "Library"
- Search for "Google Search Console API"
- Click "Enable"
4. Create OAuth credentials:
- Go to "APIs & Services" → "Credentials"
- Click "Create Credentials" → "OAuth client ID"
- Choose "Desktop application"
- Name it (e.g., "GSC-MCP")
- Click "Create"
5. Copy the **Client ID** and **Client Secret**
6. Add test users (required while app is in testing mode):
- Go to "APIs & Services" → "OAuth consent screen"
- Scroll to "Test users" section
- Click "Add users"
- Add the Google account email(s) you'll use to authenticate
- Click "Save"
> **Note:** While your app's publishing status is "Testing", only test users can authenticate. You can add up to 100 test users.
### 2. Configure GSC-MCP
Run the init command and enter your credentials:
```bash
gsc-mcp init
```
This will:
- Prompt for your Client ID and Client Secret
- Open a browser for Google authentication
- Store your refresh token securely in the OS keychain
## Usage
### CLI Commands
```bash
# Initialize with OAuth (interactive)
gsc-mcp init
# Initialize with service account
gsc-mcp init --service-account /path/to/key.json
# Initialize with full scope (for sitemap submission, URL inspection)
gsc-mcp init --scope full
# Check configuration and connectivity
gsc-mcp doctor
gsc-mcp doctor --verbose
# Start MCP server (stdio mode)
gsc-mcp run
# Start in HTTP mode (for debugging)
gsc-mcp run --http 3333
# View current configuration
gsc-mcp config
# Clear credentials
gsc-mcp logout
```
### MCP Client Configuration
#### Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"gsc": {
"command": "gsc-mcp",
"args": ["run"]
}
}
}
```
#### VS Code (Copilot)
Add to your VS Code MCP settings (`~/.vscode/mcp.json` or workspace settings):
```json
{
"servers": {
"gsc": {
"command": "gsc-mcp",
"args": ["run"],
"type": "stdio"
}
}
}
```
#### Cursor
Add to your Cursor MCP config:
```json
{
"mcpServers": {
"gsc": {
"command": "npx",
"args": ["-y", "@appsyogi/gsc-mcp-server", "run"]
}
}
}
```
## Available Tools
### Search Analytics
| Tool | Description |
|------|-------------|
| `searchanalytics.query` | Query search performance data with dimensions and filters |
| `report.comparePeriods` | Compare two time periods |
### Sitemaps
| Tool | Description | Scope |
|------|-------------|-------|
| `sitemaps.list` | List all sitemaps | readonly |
| `sitemaps.get` | Get sitemap details | readonly |
| `sitemaps.submit` | Submit a sitemap | full |
| `sitemaps.delete` | Delete a sitemap | full |
### URL Inspection
| Tool | Description | Scope |
|------|-------------|-------|
| `urlInspection.inspect` | Inspect a URL's indexing status | full |
| `urlInspection.batchInspect` | Inspect multiple URLs | full |
### SEO Opportunities
| Tool | Description |
|------|-------------|
| `opportunities.lowCtrHighPos` | Find quick-win keywords (position 4-20, low CTR) |
| `opportunities.cannibalization` | Detect keyword cannibalization |
| `report.weeklySummary` | Generate weekly performance summary |
### Export
| Tool | Description |
|------|-------------|
| `export.csv` | Export data as CSV |
| `export.json` | Export data as JSON |
## Resources
The server exposes browsable resources:
- `gsc://sites` — List all properties
- `gsc://sites/{siteUrl}/sitemaps` — List sitemaps for a property
## Scopes
GSC-MCP supports two permission levels:
### Readonly (default)
- Search analytics queries
- List sitemaps
- SEO analysis tools
```bash
gsc-mcp init # Uses readonly by default
```
### Full
- Everything in readonly, plus:
- Submit/delete sitemaps
- URL inspection
```bash
gsc-mcp init --scope full
```
## Configuration Files
GSC-MCP stores configuration in platform-specific locations:
| Platform | Config Path |
|----------|-------------|
| macOS | `~/.config/gsc-mcp/` |
| Linux | `~/.config/gsc-mcp/` |
| Windows | `%APPDATA%/gsc-mcp/` |
Files:
- `config.json` — OAuth client ID/secret, scope settings
- `cache.sqlite` — Query cache and saved presets
Tokens are stored securely in the OS keychain when available.
## Service Account Setup
For automated/server use, you can use a service account instead of OAuth:
1. Create a service account in Google Cloud Console
2. Download the JSON key file
3. Add the service account email as an owner in Google Search Console
4. Initialize:
```bash
gsc-mcp init --service-account /path/to/key.json
```
## API Quotas
Google Search Console API has a default quota of **1,200 queries per day**. GSC-MCP includes:
- Automatic retry with exponential backoff
- Query caching to reduce API calls
- Pagination handling for large result sets
## Examples
### Find Quick-Win Keywords
```
Use gsc-mcp to find quick-win opportunities for my site https://example.com
```
### Weekly Report
```
Generate a weekly performance summary for https://example.com
```
### Compare Periods
```
Compare search performance for https://example.com between last week and the week before
```
### Export Data
```
Export the top 1000 queries for https://example.com in the last 28 days as CSV
```
## Development
```bash
# Clone the repo
git clone https://github.com/AppsYogi-com/gsc-mcp-server.git
cd gsc-mcp-server
# Install dependencies
npm install
# Build
npm run build
# Run in dev mode
npm run dev
# Test locally
node dist/cli/index.js doctor
```
## License
MIT
## Contributing
Contributions are welcome! Please open an issue or PR.
## Credits
Built with:
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)
- [googleapis](https://github.com/googleapis/google-api-nodejs-client)
- [commander](https://github.com/tj/commander.js)
- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)
