🔍 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)

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

2. Deploy

Option A: Railway (Easiest)

1. Click the button above
2. 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

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

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

5. 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:

1. Fork the repository
2. Create a feature branch
3. 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!