Geo Guessr MCP

GeoGuessr MCP服务器

用于分析GeoGuessr游戏统计数据的模型上下文协议（MCP）服务器 API自动监测 和 动态模式自适应.

TODO

• \[x\] ~~修复compose文件和env变量中的Docker用户名~~
• \[x\] ~~向MCP服务器添加身份验证，仅允许特定用户访问~~
• \[\]修复未运行测试的代码质量问题
• \[\]修复黑色不格式化的代码质量问题
• \[\]添加对新端点的自动监控，并通过电子邮件发送通知

🌟 主要特点

多用户支持

• 独立会议：每个API密钥都有自己的GeoGuessr会话
• 多个帐户：不同的用户可以访问自己的GeoGuessr帐户
• 单服务器：无需为每个用户部署单独的实例
• 自动上下文：用户会话根据请求自动管理

API动态监测

• 自动端点发现：每天监控GeoGuessr API端点
• 架构更改检测：自动检测API响应格式何时更改
• 自适应：根据实际API响应更新内部数据模型
• 没有硬编码的假设：即使GeoGuessr更改其API时也有效

综合分析

• 档案和统计检索
• 游戏历史和逐轮分析
• 性能跟踪和趋势检测
• 基于游戏模式的策略建议

轻松部署

• Docker Compose用于简单的VPS部署
• 支持nginx和SSL的生产就绪
• 重启之间的持久架构缓存

🚀 快速开始

先决条件

• Docker和Docker Compose
• GeoGuessr帐户

1.克隆和配置

git clone https://github.com/NyxiumYuuki/GeoGuessrMCP.git
cd GeoGuessrMCP
cp .env.example .env

2.部署

docker compose up -d --build

就是这样！服务器现在正在端口8000上运行。

3.配置MCP服务器身份验证（可选）

要使用API密钥验证来保护MCP服务器，请编辑 .env:

MCP_AUTH_ENABLED=true
MCP_API_KEYS=your-secure-api-key-here

生成安全的API密钥：

openssl rand -hex 32

4.联系克劳德

添加到您的Claude Desktop配置中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

无身份验证：

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

使用身份验证：

{
  "mcpServers": {
    "geoguessr": {
      "type": "streamable-http",
      "url": "http://YOUR_VPS_IP:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-api-key-here"
      }
    }
  }
}

🔐 认证

服务器支持两种类型的身份验证 多用户支持:

MCP服务器身份验证（控制对MCP服务器的访问）

保护谁可以连接到您的MCP服务器。启用时，客户端必须提供有效的API密钥。

多用户支持： 每个API密钥都可以有自己的GeoGuessr会话，允许多个用户使用自己的帐户使用同一个MCP服务器实例！

启用 .env:

MCP_AUTH_ENABLED=true
MCP_API_KEYS=key1,key2,key3  # Comma-separated for multiple users

生成安全密钥：

openssl rand -hex 32

使用身份验证配置Claude Desktop：

{
  "mcpServers": {
    "geoguessr": {
      "type": "streamable-http",
      "url": "https://your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

多用户示例：

# Give each user their own API key
MCP_API_KEYS=alice_key_abc123,bob_key_def456,charlie_key_ghi789

# Alice connects with Authorization: Bearer alice_key_abc123
# Bob connects with Authorization: Bearer bob_key_def456
# Each can login to their own GeoGuessr account!

GeoGuessr API身份验证（访问GeoGuessr数据）

服务器还需要身份验证才能访问GeoGuessr的API。在多用户模式下， 每个API密钥持有者都可以登录到他们自己的GeoGuessr帐户：

选项1：通过Claude登录（推荐）

只需问克劳德：

“使用电子邮件登录GeoGuessr：myemail@example.com密码：mypassword“

选项2：环境变量

添加到您的 .env 文件：

GEOGUESSR_NCFA_COOKIE=your_cookie_value_here

选项3：手动Cookie

使用 set_ncfa_cookie 从浏览器中提取cookie的工具。

👥 多用户模式

该服务器支持多个用户，每个用户都有自己的GeoGuessr帐户，使用单个MCP服务器实例。

运作原理

1. API密钥：每个用户都获得一个唯一的API密钥
2. 独立会议：每个API密钥都有自己的GeoGuessr登录会话
3. 自动路由：服务器会自动将请求路由到正确的用户会话
4. 不干涉：用户不会影响彼此的会话

设置示例

1.配置多个API密钥：

# .env file
MCP_AUTH_ENABLED=true
MCP_API_KEYS=alice_key,bob_key,charlie_key

2.重新启动服务器：

# Development
docker compose restart

# Production
docker compose -f docker-compose.prod.yml restart

3.每个用户连接：

// Alice's Claude Desktop config
{
  "mcpServers": {
    "geoguessr": {
      "url": "https://your-domain.com/mcp",
      "headers": {"Authorization": "Bearer alice_key"}
    }
  }
}

// Bob's Claude Desktop config
{
  "mcpServers": {
    "geoguessr": {
      "url": "https://your-domain.com/mcp",
      "headers": {"Authorization": "Bearer bob_key"}
    }
  }
}

4.每个用户登录：

• 爱丽丝问克劳德：“用我的凭据登录GeoGuessr”
• Bob问Claude：“使用我的凭据登录GeoGuessr”
• 会议是完全独立的！

添加新用户

要将新用户添加到现有部署中，请执行以下操作：

1. 编辑 .env 并将新的API密钥添加到 MCP_API_KEYS
2. 重新启动服务器： docker compose restart
3. 与用户共享新的API密钥
4. 用户使用API键配置Claude Desktop
5. 用户通过Claude登录其GeoGuessr帐户

服务器将在2-3秒内重新启动 所有现有用户仍保持登录！

📊 可用工具

认证

个人资料和统计数据

游戏与活动

分析

API监测

🔄 动态模式系统

服务器自动适应API的更改：

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

运作原理

1. 日常监控：服务器每24小时检查一次所有已知端点
2. 模式检测：分析响应结构、字段类型和嵌套
3. 变化检测：计算架构哈希以检测修改
4. 持久性：架构缓存到磁盘并在重新启动后继续存在
5. 动态访问：工具返回带有LLM架构信息的数据

示例：探索未知端点

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

🏭 生产部署

服务器可以作为预构建的Docker镜像使用： nyxiumyuuki/geoguessr-mcp:latest

方法1：使用脚本快速部署

对于使用现有nginx代理管理器的VPS部署：

# Clone repository on VPS
git clone https://github.com/NyxiumYuuki/GeoGuessrMCP.git
cd GeoGuessrMCP

# Configure environment
cp .env.example .env
# Edit .env with your settings:
# - GEOGUESSR_NCFA_COOKIE (for GeoGuessr API access)
# - MCP_AUTH_ENABLED=true (optional, for MCP server security)
# - MCP_API_KEYS (if authentication enabled)

# Run deployment script
./scripts/deploy.sh

方法2：手动Docker编写部署

开发/测试设置

# Using docker-compose.yml (development)
docker compose up -d

使用nginx代理管理器进行生产设置

# Using docker-compose.prod.yml (production)
docker compose -f docker-compose.prod.yml up -d

在nginx代理管理器中配置SSL：

• 访问管理面板： http://your-vps-ip:81
• 为您的域添加代理主机
• 转发至： geoguessr-mcp-server:8000
• 使用Let’s Encrypt启用SSL

📖 有关VPS部署的详细说明，请参阅 部署.md

方法3：直接运行Docker

如果你不想使用Docker Compose：

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

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

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

# Run with MCP authentication enabled
docker run -d \
  --name geoguessr-mcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -e GEOGUESSR_NCFA_COOKIE=your_cookie \
  -e MCP_AUTH_ENABLED=true \
  -e MCP_API_KEYS=your-api-key-1,your-api-key-2 \
  -e MONITORING_ENABLED=true \
  -e MONITORING_INTERVAL_HOURS=24 \
  -e LOG_LEVEL=INFO \
  -v geoguessr-schemas:/app/data/schemas \
  nyxiumyuuki/geoguessr-mcp:latest

环境变量

🧪 发展

本地开发

# 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

项目结构

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

🤝 贡献

欢迎投稿！拜托：

1. 复刻仓库
2. 创建要素分支
3. 添加新功能的测试
4. 提交拉取请求

📝 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

⚠️ 免责声明

本项目使用非官方的GeoGuessr API，可能会更改，恕不另行通知。动态模式系统有助于缓解这种情况，但如果GeoGuessr对API进行重大更改，某些功能可能会中断。

该项目不隶属于GeoGuessr AB。