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.