GSC MCP Server v2 - Remote Edition

# 🔍 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](https://console.cloud.google.com/) 2. Create a new project or select existing 3. Enable APIs: - [Search Console API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com) - [Indexing API](https://console.cloud.google.com/apis/library/indexing.googleapis.com) (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) [](https://railway.app/template) 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 ```bash # 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 ```bash # 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**: ```json { "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](LICENSE) file. ## 👨‍💻 Author **Amin Foroutan** - SEO Consultant & Developer - 🌐 [aminforoutan.com](https://aminforoutan.com/) - 💼 [LinkedIn](https://www.linkedin.com/in/ma-foroutan/) - 🐦 [Twitter](https://x.com/aminfseo) - 📺 [YouTube](https://www.youtube.com/channel/UCW7tPXg-rWdH4YzLrcAdBIw) --- ⭐ If you find this useful, please star the repo!