GeoGuessr MCP Server

A Model Context Protocol (MCP) server for analyzing your GeoGuessr account data. This server allows Claude AI to access and analyze your GeoGuessr statistics, game history, achievements, and more.

Authentication Options

The server supports three authentication methods:

1. Login with credentials (Recommended) - Use the login tool with your GeoGuessr email and password
2. Manual cookie - Use the set_ncfa_cookie tool with a cookie extracted from your browser
3. Environment variable - Set GEOGUESSR_NCFA_COOKIE for server-wide default authentication

Using Login (Easiest)

Simply ask Claude to login:

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

The server will authenticate with GeoGuessr and create a session. Your credentials are only used once to obtain an authentication token - they are not stored on the server.

Security Notes

• Credentials are sent directly to GeoGuessr's official API over HTTPS
• Session tokens are stored in memory only (lost on server restart)
• For persistent authentication, use the environment variable method
• Always use HTTPS in production to protect credentials in transit

Features

Authentication Tools

• login - Authenticate with email/password
• logout - End the current session
• set_ncfa_cookie - Set authentication cookie manually
• set_session_token - Restore a previous session
• get_auth_status - Check current authentication status

Profile & Stats

• get_my_profile - Get your user profile information
• get_my_stats - Get detailed statistics displayed on your profile
• get_extended_stats - Get additional stats not shown on profile
• get_my_achievements - Get all your achievements
• get_my_trophies - Get your trophy collection
• get_trophy_case - Get your displayed trophy case

Games & Activity

• get_activity_feed - Get recent activity (games, achievements, etc.)
• get_game_details - Get detailed info about a specific game
• get_unfinished_games - Get games you haven't completed
• get_streak_game - Get country streak game details
• analyze_recent_games - Analyze your recent games with statistics

Competitive Modes

• get_battle_royale_game - Get Battle Royale game stats
• get_duel_game - Get duel game information
• get_game_lobby - Get lobby info with player stats
• get_current_season_stats - Get current season statistics
• get_season_game_info - Get season info for specific game modes
• get_tournaments - Get tournament information

Challenges

• get_daily_challenge - Get today's or previous daily challenges
• get_challenge_details - Get details about a specific challenge

Social

• get_friends - Get your friends list
• get_friends_summary - Get friends with requests and recommendations
• get_notifications - Get your notifications
• search_user - Search for other players

Maps

• get_my_maps - Get maps you've created
• get_liked_maps - Get maps you've liked
• get_map_info - Get info about any map
• get_popular_maps - Get popular/featured/official maps
• get_personalized_maps - Get map recommendations
• get_map_scores - Get high scores for a map

Explorer & Progress

• get_explorer_progress - Get your explorer mode progress
• get_objectives - Get current objectives
• get_unclaimed_objectives - Get rewards to claim
• get_unclaimed_badges - Get badges to claim

Analysis

• get_performance_summary - Get comprehensive performance overview

Prerequisites

• Docker and Docker Compose installed on your VPS
• A GeoGuessr account (Pro subscription recommended for full API access)
• Your GeoGuessr _ncfa authentication cookie

Quick Start

1. Clone or copy the files to your VPS

mkdir -p ~/geoguessr-mcp
cd ~/geoguessr-mcp
# Copy all the files here

2. Build and run (no configuration required!)

docker compose up -d --build

That's it! The server now supports login via credentials, so you don't need to configure anything upfront.

3. (Optional) Configure default authentication

If you want server-wide default authentication without logging in each time:

Option A: Get your GeoGuessr authentication cookie

1. Log in to GeoGuessr in your browser
2. Open Developer Tools (F12 or Ctrl+Shift+I)
3. Go to the Application tab (Chrome) or Storage tab (Firefox)
4. Under Cookies, find www.geoguessr.com
5. Look for the cookie named _ncfa
6. Copy its value

cp .env.example .env
nano .env  # Add your cookie

GEOGUESSR_NCFA_COOKIE=your_actual_cookie_value_here

Option B: Just use login when connected

When connected to Claude, simply say:

"Login to GeoGuessr with my email and password"

Claude will prompt you for credentials and authenticate.

4. Restart if you added environment variables

docker compose up -d --build

5. Verify it's running

docker compose logs -f

You should see:

Starting GeoGuessr MCP Server on 0.0.0.0:8000 with streamable-http transport

Connecting to Claude

Claude Desktop (macOS/Windows)

Add to your Claude Desktop configuration file:

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"
    }
  }
}

VS Code with Copilot

1. Open VS Code
2. Run the command: MCP: Add Server
3. Choose "HTTP (Streamable HTTP)" as the transport
4. Enter URL: http://YOUR_VPS_IP:8000/mcp

Claude.ai (if MCP support is enabled)

Add the server through Claude.ai's integrations settings with:

• URL: http://YOUR_VPS_IP:8000/mcp
• Transport: Streamable HTTP

Using with Claude

Once connected, you can ask Claude questions like:

First, authenticate (if not using environment variable):

• "Login to GeoGuessr with email: myemail@example.com password: mypassword"
• "Check my GeoGuessr authentication status"

Then analyze your data:

• "Show me my GeoGuessr profile and stats"
• "Analyze my last 10 games and tell me how I'm doing"
• "What achievements have I unlocked?"
• "How am I doing in the current competitive season?"
• "Show me my activity feed from the last week"
• "What maps have I liked?"
• "Search for a player named [username]"
• "Get the details of my last Battle Royale game"

When done (optional):

• "Logout from GeoGuessr"

Production Deployment

Adding SSL with Nginx (Recommended)

For production, you should add SSL. Create an nginx.conf:

events {
    worker_connections 1024;
}

http {
    upstream mcp_server {
        server geoguessr-mcp:8000;
    }

    server {
        listen 80;
        server_name your-domain.com;
        return 301 https://$server_name$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name your-domain.com;

        ssl_certificate /etc/nginx/ssl/fullchain.pem;
        ssl_certificate_key /etc/nginx/ssl/privkey.pem;

        location / {
            proxy_pass http://mcp_server;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_read_timeout 86400;
        }
    }
}

Adding API Key Authentication

For additional security, you can add API key authentication. Modify the server.py to check for an x-api-key header.

Firewall Configuration

# Allow only specific IPs or use a firewall
sudo ufw allow from YOUR_IP to any port 8000

Troubleshooting

"GEOGUESSR_NCFA_COOKIE environment variable not set"

Make sure your .env file exists and contains the cookie:

cat .env | grep GEOGUESSR

Cookie expired

GeoGuessr cookies expire periodically. If API calls start failing, get a fresh cookie from your browser.

Connection refused

1. Check if the container is running: docker compose ps
2. Check logs: docker compose logs geoguessr-mcp
3. Verify the port is exposed: docker port geoguessr-mcp-server

API rate limiting

GeoGuessr may rate-limit excessive API calls. Space out requests if you're hitting limits.

Cookie Security

⚠️ Important Security Notes:

1. The _ncfa cookie provides full access to your GeoGuessr account
2. Never share your .env file or commit it to version control
3. Consider running the server on a private network
4. Use SSL in production
5. Regularly rotate your cookie

Development

To run locally without Docker:

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Set environment variable
export GEOGUESSR_NCFA_COOKIE="your_cookie_here"

# Run the server
python server.py

API Reference

The server uses the unofficial GeoGuessr API. Key endpoints:

• https://www.geoguessr.com/api/v3/ - Main API (v3)
• https://www.geoguessr.com/api/v4/ - Newer API (v4)
• https://game-server.geoguessr.com/api/ - Game server API

Note: This is an unofficial API and may change without notice.

License

MIT License - Feel free to modify and distribute.

Disclaimer

This project is not affiliated with, endorsed by, or connected to GeoGuessr AB. Use at your own risk and in accordance with GeoGuessr's Terms of Service.