Init Commit
This commit is contained in:
Yûki VACHOT
commit
ce5abcc217
19 changed files with 2526 additions and 0 deletions
335
README.md
Normal file
335
README.md
Normal file
|
|
@ -0,0 +1,335 @@
|
|||
# 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
|
||||
|
||||
```bash
|
||||
mkdir -p ~/geoguessr-mcp
|
||||
cd ~/geoguessr-mcp
|
||||
# Copy all the files here
|
||||
```
|
||||
|
||||
### 2. Build and run (no configuration required!)
|
||||
|
||||
```bash
|
||||
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](https://www.geoguessr.com) 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
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
nano .env # Add your cookie
|
||||
```
|
||||
|
||||
```env
|
||||
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
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
### 5. Verify it's running
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
```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`:
|
||||
|
||||
```nginx
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue