home / mcp / geoguessr mcp server
Provides a scalable, self-adapting MCP server for GeoGuessr data with multi-user sessions and automatic API monitoring.
Configuration
View docs{
"mcpServers": {
"nyxiumyuuki-geoguessrmcp": {
"url": "http://YOUR_VPS_IP:8000/mcp",
"headers": {
"MCP_API_KEYS": "alice_key,bob_key",
"MCP_AUTH_ENABLED": "true",
"GEOGUESSR_NCFA_COOKIE": "<cookie_value>"
}
}
}
}You run a Model Context Protocol (MCP) server that analyzes GeoGuessr game statistics with automatic API monitoring and dynamic schema adaptation. It lets multiple users share a single server instance while keeping their own sessions, automatically discovers API endpoints, and provides rich profile, stats, and strategy insights.
Set up the MCP server once, then connect your MCP client (such as Claude) to your server URL. If you enable multi-user authentication, each user uses their own API key and GeoGuessr login, with sessions isolated per key. You can monitor API health, view endpoint schemas, and run analysis tools to get performance trends and tailored improvement suggestions. Use the HTTP connection for remote access or the local stdio connection for running the server on the same host.
- Multi-User Mode: generate a unique API key per user and share it securely. Each user obtains an independent GeoGuessr session on the same MCP server. The server routes requests to the correct user session automatically. - API Monitoring: the server checks known GeoGuessr endpoints daily, detects schema changes, and updates internal models so you can rely on up-to-date responses even if the API shifts.
# Prerequisites
# - Docker and Docker Compose installed
# - A GeoGuessr account
# 1. Clone and configure
git clone https://github.com/NyxiumYuuki/GeoGuessrMCP.git
cd GeoGuessrMCP
cp .env.example .env
# 2. Deploy (development setup shown; production uses docker-compose.prod.yml)
docker compose up -d --build
# 3. (Optional) Enable authentication
# In .env, set MCP_AUTH_ENABLED and MCP_API_KEYS as needed
# - Example
# MCP_AUTH_ENABLED=true
# MCP_API_KEYS=alice_key,bob_key
# 4. Connect with your MCP client
# Use the HTTP URL below or the local stdio command if you run it directlyConfiguration and security details are built into the server setup. You can enable authentication to restrict access to the MCP server and limit usage to specific API keys. To connect clients securely, include the Authorization: Bearer <API_KEY> header in your client requests.
Dynamic schema and daily API monitoring keep your data models aligned with GeoGuessr responses. Schemas are cached on disk so restarts don’t lose your adaptation history, and tools expose endpoint data with its associated schema for reliable processing.
Deployment options include a pre-built Docker image and two deployment methods: a quick script for VPS setups with nginx-proxy-manager and a manual Docker Compose workflow for development and production. SSL can be configured via your proxy manager for secure access.
Environment variables you may configure include the GeoGuessr authentication cookie, MCP authentication settings, monitoring controls, and logging level. Adjust these values to fit your infrastructure and security requirements.
This guide includes practical commands for running the server locally and deploying in production. Use the following entry points to start or configure access to the MCP server.
Authenticate with GeoGuessr credentials or via Claude integration to initiate an account session
End the current MCP session and clear authentication context
Manually set the GeoGuessr NCFA cookie for API access
Retrieve the authenticated user’s GeoGuessr profile information
Fetch the authenticated user’s game statistics
Retrieve the latest activity for the authenticated user