🔍 GSC MCP Server v2 - Remote Edition

A hosted MCP server that connects Claude AI to Google Search Console with OAuth 2.0 web authentication. Users simply sign in with Google—no API keys or credentials to manage!

✨ What's Different About v2?

Feature	v1 (Local)	v2 (Remote)
Authentication	Local credentials file	OAuth 2.0 web flow
Setup	Complex	Just sign in with Google!
Hosting	Your machine	Any cloud platform
Multi-user	Single user	Multiple users supported

🏗️ Architecture

┌─────────────────┐     OAuth 2.0      ┌──────────────────────┐
│     User's      │ ──────────────────→│   Your Hosted        │
│     Browser     │←──────────────────→│   MCP Server         │
└─────────────────┘                    └──────────────────────┘
                                                 ↓
┌─────────────────┐    MCP over SSE    ┌──────────────────────┐
│  Claude Desktop │ ←─────────────────→│  Stored User Token   │
└─────────────────┘                    └──────────────────────┘
                                                 ↓
                                       ┌──────────────────────┐
                                       │  Google Search       │
                                       │  Console API         │
                                       └──────────────────────┘

🚀 Quick Start

1. Set Up Google OAuth (Web Application)

Go to Google Cloud Console
Create a new project or select existing
Enable APIs:
- Search Console API
- Indexing API (optional)
Go to Credentials → Create Credentials → OAuth client ID
Select Web application
Add authorized redirect URI: https://your-domain.com/oauth/callback
Save your Client ID and Client Secret

2. Deploy

Option A: Railway (Easiest)

Click the button above
Set environment variables:
- GOOGLE_CLIENT_ID
- GOOGLE_CLIENT_SECRET
- GOOGLE_REDIRECT_URI (your Railway URL + /oauth/callback)
- BASE_URL (your Railway URL)

Option B: Docker

# Build
docker build -t gsc-mcp-server .

# Run
docker run -p 8000:8000 \
  -e GOOGLE_CLIENT_ID="your-client-id" \
  -e GOOGLE_CLIENT_SECRET="your-secret" \
  -e GOOGLE_REDIRECT_URI="https://your-domain.com/oauth/callback" \
  -e BASE_URL="https://your-domain.com" \
  -v ./data:/app/data \
  gsc-mcp-server

Option C: Manual

# Clone
git clone https://github.com/AminForou/google-search-console-mcp-v2.git
cd google-search-console-mcp-v2

# Install
pip install -r requirements.txt

# Set environment variables
export GOOGLE_CLIENT_ID="your-client-id"
export GOOGLE_CLIENT_SECRET="your-secret"
export GOOGLE_REDIRECT_URI="http://localhost:8000/oauth/callback"

# Run
uvicorn gsc_server_remote:app --host 0.0.0.0 --port 8000

3. User Flow

Users visit your server → https://your-domain.com
Click "Sign in with Google" → OAuth flow
Get unique API key → Displayed after login
Configure Claude Desktop:

{
  "mcpServers": {
    "gscServer": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-domain.com/mcp/USER_API_KEY/sse"]
    }
  }
}

Start chatting! → "List my GSC properties"

🛠️ Available Tools

Tool	Description
`list_properties`	List all GSC properties
`get_search_analytics`	Search performance data
`get_performance_overview`	Performance summary
`find_keyword_opportunities`	Find ranking opportunities
`get_top_pages`	Top performing pages
`get_device_comparison`	Mobile vs desktop
`get_country_breakdown`	Traffic by country
`inspect_url`	URL indexing status
`get_sitemaps`	List sitemaps
`submit_sitemap`	Submit new sitemap
`request_indexing`	Request URL indexing
`export_analytics`	Export to CSV/JSON

🔒 Security Considerations

HTTPS Required: Always use HTTPS in production
API Keys: Each user gets a unique key - treat it like a password
Token Storage: Uses SQLite by default - use PostgreSQL for production
CORS: Restrict origins in production
Rate Limiting: Add rate limiting for production

📁 Project Structure

google-search-console-mcp-v2/
├── gsc_server_remote.py    # Main server application
├── requirements.txt        # Python dependencies
├── Dockerfile             # Docker configuration
├── .gitignore            # Git ignore rules
└── README.md             # This file

🌐 Environment Variables

Variable	Required	Description
`GOOGLE_CLIENT_ID`	✅	OAuth client ID
`GOOGLE_CLIENT_SECRET`	✅	OAuth client secret
`GOOGLE_REDIRECT_URI`	✅	OAuth callback URL
`BASE_URL`	⚡	Public server URL
`SECRET_KEY`	⚡	Session encryption key
`DATABASE_PATH`	❌	SQLite path (default: gsc_tokens.db)

📊 API Endpoints

Endpoint	Method	Description
`/`	GET	Home page with login
`/oauth/login`	GET	Start OAuth flow
`/oauth/callback`	GET	OAuth callback
`/oauth/revoke/{user_id}`	GET	Revoke user access
`/mcp/{user_id}/sse`	GET	MCP SSE endpoint
`/health`	GET	Health check
`/api/status/{user_id}`	GET	User auth status

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Submit a pull request

📄 License

MIT License - see LICENSE file.

👨‍💻 Author

Amin Foroutan - SEO Consultant & Developer

🌐 aminforoutan.com
💼 LinkedIn
🐦 Twitter
📺 YouTube

⭐ If you find this useful, please star the repo!