GeoGuessr MCP Server

A Model Context Protocol (MCP) server for analyzing GeoGuessr game statistics with automatic API monitoring and dynamic schema adaptation.

🌟 Key Features

Dynamic API Monitoring

• Automatic endpoint discovery: Monitors GeoGuessr API endpoints daily
• Schema change detection: Automatically detects when API response formats change
• Self-adapting: Updates internal data models based on actual API responses
• No hardcoded assumptions: Works even when GeoGuessr changes their API

Comprehensive Analysis

• Profile and statistics retrieval
• Game history and round-by-round analysis
• Performance tracking and trend detection
• Strategy recommendations based on gameplay patterns

Easy Deployment

• Docker Compose for simple VPS deployment
• Production-ready with nginx and SSL support
• Persistent schema caching between restarts

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• A GeoGuessr account

1. Clone and Configure

git clone https://github.com/yourusername/geoguessr-mcp.git
cd geoguessr-mcp
cp .env.example .env

2. Deploy

docker compose up -d --build

That's it! The server is now running on port 8000.

3. Connect to Claude

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "geoguessr": {
      "type": "streamable-http",
      "url": "http://YOUR_VPS_IP:8000/mcp"
    }
  }
}

🔐 Authentication

The server supports multiple authentication methods:

Option 1: Login via Claude (Recommended)

Simply ask Claude:

"Login to GeoGuessr with email: myemail@example.com and password: mypassword"

Option 2: Environment Variable

Add to your .env file:

GEOGUESSR_NCFA_COOKIE=your_cookie_value_here

Option 3: Manual Cookie

Use the set_ncfa_cookie tool with a cookie extracted from your browser.

📊 Available Tools

Authentication

Tool	Description
login	Authenticate with email/password
logout	End current session
set_ncfa_cookie	Set authentication cookie manually
get_auth_status	Check authentication status

Profile & Stats

Tool	Description
get_my_profile	Get your profile information
get_my_stats	Get your game statistics
get_extended_stats	Get additional statistics
get_achievements	Get your achievements
get_comprehensive_profile	Get combined profile data

Games & Activity

Tool	Description
get_activity_feed	Get recent activity
get_recent_games	Get recent games with details
get_game_details	Get specific game information
get_season_stats	Get competitive season stats
get_daily_challenge	Get daily challenge info

Analysis

Tool	Description
analyze_recent_games	Analyze performance trends
get_performance_summary	Comprehensive performance overview
get_strategy_recommendations	Get personalized improvement tips

API Monitoring

Tool	Description
check_api_status	Check all endpoint availability
get_endpoint_schema	Get schema for specific endpoint
list_available_endpoints	List all known endpoints
explore_endpoint	Discover new API endpoints

🔄 Dynamic Schema System

The server automatically adapts to API changes:

┌─────────────────────┐      ┌──────────────────┐
│   API Response      │ ───▶ │  Schema Detector │
└─────────────────────┘      └────────┬─────────┘
                                      │
                                      ▼
┌─────────────────────┐      ┌──────────────────┐
│  Schema Registry    │ ◀─── │  Compare Hash    │
│  (Persisted)        │      └──────────────────┘
└─────────────────────┘
         │
         ▼
┌─────────────────────┐
│  Dynamic Response   │ ───▶ Available to LLM
│  with Schema Info   │
└─────────────────────┘

How It Works

1. Daily Monitoring: The server checks all known endpoints every 24 hours
2. Schema Detection: Analyzes response structure, field types, and nesting
3. Change Detection: Computes schema hash to detect modifications
4. Persistence: Schemas are cached to disk and survive restarts
5. Dynamic Access: Tools return data with schema information for the LLM

Example: Exploring Unknown Endpoints

User: "Can you explore the /v3/some-new-endpoint API?"

Claude uses explore_endpoint tool:
{
  "success": true,
  "discovered_fields": ["id", "name", "data", "timestamp"],
  "schema_description": "Endpoint: /v3/some-new-endpoint\nFields:\n  - id: string\n  - name: string\n  - data: object\n  - timestamp: datetime"
}

🏭 Production Deployment

Method 1: Build and Push Docker Image

For VPS deployment, it's recommended to build and push your image to Docker Hub:

# 1. Build the image
docker build -t yourusername/geoguessr-mcp:latest .

# 2. Login to Docker Hub
docker login

# 3. Push the image
docker push yourusername/geoguessr-mcp:latest

# 4. On your VPS, pull and run
docker pull yourusername/geoguessr-mcp:latest

Method 2: Deploy with Docker Compose on VPS

Development/Testing Setup

# Clone repository on VPS
git clone https://github.com/yourusername/geoguessr-mcp.git
cd geoguessr-mcp

# Create .env file
cat > .env << EOF
GEOGUESSR_NCFA_COOKIE=your_cookie_here
DOCKER_USERNAME=yourusername
IMAGE_TAG=latest
EOF

# Deploy
docker compose up -d

Production Setup with SSL

1. Create SSL certificates:

mkdir -p nginx/ssl
# Add your certificates:
# nginx/ssl/fullchain.pem
# nginx/ssl/privkey.pem

2. Update docker-compose.prod.yml to use your Docker image:

# Edit docker-compose.prod.yml and uncomment the image line:
# image: ${DOCKER_USERNAME:-yourusername}/geoguessr-mcp:${IMAGE_TAG:-latest}
# Then comment out the build section

3. Deploy with production compose:

docker compose -f docker-compose.prod.yml up -d

Method 3: Direct Docker Run

If you prefer not to use Docker Compose:

# Pull the image
docker pull yourusername/geoguessr-mcp:latest

# Create a volume for schema cache
docker volume create geoguessr-schemas

# Run the container
docker run -d \
  --name geoguessr-mcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -e GEOGUESSR_NCFA_COOKIE=your_cookie \
  -e MONITORING_ENABLED=true \
  -e MONITORING_INTERVAL_HOURS=24 \
  -e LOG_LEVEL=INFO \
  -v geoguessr-schemas:/app/data/schemas \
  yourusername/geoguessr-mcp:latest

Building Multi-Architecture Images

For deployment on different CPU architectures (ARM64, AMD64):

# Enable buildx
docker buildx create --use

# Build and push multi-arch image
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t yourusername/geoguessr-mcp:latest \
  --push .

Environment Variables

Variable	Default	Description
GEOGUESSR_NCFA_COOKIE	-	Default authentication cookie
MCP_PORT	8000	Server port
MCP_TRANSPORT	streamable-http	MCP transport protocol
MONITORING_ENABLED	true	Enable API monitoring
MONITORING_INTERVAL_HOURS	24	Monitoring check interval (runs every 24h)
SCHEMA_CACHE_DIR	/app/data/schemas	Directory for schema persistence
LOG_LEVEL	INFO	Logging verbosity
DOCKER_USERNAME	yourusername	Your Docker Hub username (for compose files)
IMAGE_TAG	latest	Docker image tag

🧪 Development

Local Development

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements-dev.txt

# Run tests
pytest -v

# Run server locally
python -m geoguessr_mcp.main

Project Structure

geoguessr-mcp/
├── src/geoguessr_mcp/
│   ├── api/              # API client and endpoints
│   ├── auth/             # Authentication
│   ├── models/           # Data models
│   ├── monitoring/       # Schema detection & monitoring
│   ├── services/         # Business logic
│   ├── tools/            # MCP tool definitions
│   ├── config.py         # Configuration
│   └── main.py           # Entry point
├── tests/
│   ├── unit/             # Unit tests
│   └── integration/      # Integration tests
├── nginx/                # Production nginx config
├── docker-compose.yml    # Development deployment
├── docker-compose.prod.yml # Production deployment
└── Dockerfile

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

📝 License

MIT License - see LICENSE file for details.

⚠️ Disclaimer

This project uses the unofficial GeoGuessr API which may change without notice. The dynamic schema system helps mitigate this, but some features may break if GeoGuessr makes significant API changes.

This project is not affiliated with GeoGuessr AB.