GSC MCP Server

A Model Context Protocol (MCP) server for Google Search Console. Query your search analytics, inspect URLs, and manage sitemaps directly from Claude, ChatGPT, or any MCP client.

Want a hosted solution? Ekamoira offers a fully-managed GSC MCP server with OAuth authentication, no setup required. Just connect your Google account and start querying.

Features

• Search Analytics: Query clicks, impressions, CTR, and position data with flexible filtering
• Site Management: List all your GSC properties with permission levels
• URL Inspection: Check indexing status, crawl issues, and mobile usability
• Sitemap Management: List, submit, and delete sitemaps

Quick Start

Prerequisites

1. Node.js 20+
2. A Google Cloud project with Search Console API enabled
3. OAuth 2.0 credentials (Desktop app type)

Installation

git clone https://github.com/soumyadeep-ux/gsc-mcp-server.git
cd gsc-mcp-server
npm install
cp .env.example .env

Edit .env with your Google credentials:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

First-Time Authentication

npm run auth

This opens your browser for Google OAuth consent and saves the token locally.

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/absolute/path/to/gsc-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-secret"
      }
    }
  }
}

Build and restart Claude Desktop:

npm run build
# Restart Claude Desktop

Connect to Cursor

# Add via CLI
npx cursor-mcp add gsc-mcp-server node /absolute/path/to/gsc-mcp-server/dist/index.js

Available Tools

| Tool | Description | |------|-------------| | gsc.list_sites | List all your GSC properties with permission levels | | gsc.search_analytics | Query search performance data with filters | | gsc.inspect_url | Check URL indexing status, crawl info, and mobile usability | | gsc.list_sitemaps | List all submitted sitemaps with status | | gsc.submit_sitemap | Submit a new sitemap | | gsc.delete_sitemap | Remove a sitemap |

Example Prompts

Try these prompts in Claude:

• "List all my Search Console sites"
• "What are my top 10 keywords by clicks this month?"
• "Show me queries with more than 1000 impressions but CTR below 2%"
• "What keywords are driving traffic to my /blog page?"
• "Compare my search performance for the last 7 days vs the previous 7 days"
• "Is https://example.com/pricing indexed by Google?"
• "Check the indexing status of my homepage"
• "List all sitemaps submitted to my site"
• "Submit https://example.com/sitemap.xml to Search Console"

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_CLIENT_ID | Yes | Google OAuth 2.0 Client ID | | GOOGLE_CLIENT_SECRET | Yes | Google OAuth 2.0 Client Secret | | GSC_SERVICE_ACCOUNT_PATH | No | Path to service account JSON (alternative to OAuth) | | GSC_TOKEN_PATH | No | Token storage path (default: ./token.json) | | GSC_DEFAULT_SITE | No | Default GSC property URL | | GSC_LOG_LEVEL | No | Log level: debug/info/warn/error (default: info) |

Service Account Authentication

For automated/server environments, you can use a service account instead of OAuth:

1. Create a service account in Google Cloud Console
2. Grant it access in Google Search Console (add as user)
3. Download the JSON key file
4. Set GSC_SERVICE_ACCOUNT_PATH in your environment

GSC_SERVICE_ACCOUNT_PATH=/path/to/service-account.json

Development

npm run dev        # Watch mode with hot reload
npm run build      # Compile TypeScript
npm run lint       # Check code style
npm run typecheck  # Type checking
npm run test       # Run tests

Testing with MCP Inspector

npm run build
npm run inspector

Alternatives

| Option | Best For | Link | |--------|----------|------| | This repo | Developers who want full control and self-hosting | You're here! | | Ekamoira GSC MCP | Users who want zero setup, works immediately | app.ekamoira.com/tools/gsc |

Ekamoira's Hosted Solution

If you don't want to manage credentials or run your own server, Ekamoira offers:

• One-click Google OAuth connection
• No local setup or credentials management
• Works with Claude.ai, ChatGPT, Claude Desktop, and Cursor
• 30-day free trial
• Additional SEO tools beyond GSC

Troubleshooting

"Token expired" errors

rm token.json
npm run auth

"API not enabled" error

1. Go to Google Cloud Console
2. APIs & Services > Enable APIs
3. Search for "Search Console API"
4. Click Enable

"Permission denied" errors

• Verify you have access to the GSC property
• Check that OAuth scopes include webmasters
• Try re-authenticating with npm run auth

Claude Desktop not showing tools

1. Verify JSON syntax in config file
2. Use absolute paths (not relative)
3. Restart Claude Desktop completely
4. Check logs at ~/Library/Logs/Claude/ (macOS)

Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Run npm run lint && npm run typecheck && npm test
5. Submit a PR

License

MIT

Credits

Built with the Model Context Protocol SDK.

Inspired by Ekamoira, an AI-powered SEO platform.