Geoguessrmcp

🚀 GeoGuessr MCP 服务器

GeoGuessr MCP 服务器是一个基于模型上下文协议（MCP）的服务器，用于分析 GeoGuessr 游戏统计数据。它具备自动 API 监控和动态模式自适应功能，能有效应对 GeoGuessr API 的变化，为用户提供稳定、全面的游戏数据分析服务。

📋 待办事项

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

✨ 主要特性

多用户支持

• 独立会话：每个 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

将以下内容添加到 Claude 桌面配置文件中：

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

有身份验证：

{
  "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  # 多个用户的 API 密钥用逗号分隔

生成安全密钥：

openssl rand -hex 32

在 Claude 桌面配置中使用身份验证：

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

多用户示例：

# 为每个用户分配自己的 API 密钥
MCP_API_KEYS=alice_key_abc123,bob_key_def456,charlie_key_ghi789

# Alice 使用 Authorization: Bearer alice_key_abc123 连接
# Bob 使用 Authorization: Bearer bob_key_def456 连接
# 每个用户都可以登录自己的 GeoGuessr 账户！

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

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

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

只需向 Claude 发出请求：

"使用邮箱 myemail@example.com 和密码 mypassword 登录 GeoGuessr"

选项 2：使用环境变量

在 .env 文件中添加以下内容：

GEOGUESSR_NCFA_COOKIE=your_cookie_value_here

选项 3：手动设置 Cookie

使用 set_ncfa_cookie 工具，并从浏览器中提取 Cookie。

👥 多用户模式

服务器支持多个用户使用同一 MCP 服务器实例，每个用户都可以使用自己的 GeoGuessr 账户。

工作原理

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

设置示例

1. 配置多个 API 密钥：

# .env 文件
MCP_AUTH_ENABLED=true
MCP_API_KEYS=alice_key,bob_key,charlie_key

2. 重启服务器：

# 开发环境
docker compose restart

# 生产环境
docker compose -f docker-compose.prod.yml restart

3. 每个用户进行连接：

// Alice 的 Claude 桌面配置
{
  "mcpServers": {
    "geoguessr": {
      "url": "https://your-domain.com/mcp",
      "headers": {"Authorization": "Bearer alice_key"}
    }
  }
}

// Bob 的 Claude 桌面配置
{
  "mcpServers": {
    "geoguessr": {
      "url": "https://your-domain.com/mcp",
      "headers": {"Authorization": "Bearer bob_key"}
    }
  }
}

4. 每个用户进行登录：

• Alice 向 Claude 请求："使用我的凭据登录 GeoGuessr"
• Bob 向 Claude 请求："使用我的凭据登录 GeoGuessr"
• 会话完全独立！

添加新用户

若要向现有部署中添加新用户，请按以下步骤操作：

1. 编辑 .env 文件，将新的 API 密钥添加到 MCP_API_KEYS 中。
2. 重启服务器：docker compose restart
3. 将新的 API 密钥分享给用户。
4. 用户使用 API 密钥配置其 Claude 桌面。
5. 用户通过 Claude 登录其 GeoGuessr 账户。

服务器将在约 2 - 3 秒内重启，所有现有用户仍保持登录状态！

📊 可用工具

身份验证

工具	描述
login	使用电子邮件/密码进行身份验证
logout	结束当前会话
set_ncfa_cookie	手动设置身份验证 Cookie
get_auth_status	检查身份验证状态

个人资料与统计信息

工具	描述
get_my_profile	获取您的个人资料信息
get_my_stats	获取您的游戏统计数据
get_extended_stats	获取额外的统计信息
get_achievements	获取您的成就信息
get_comprehensive_profile	获取综合个人资料数据

游戏与活动

工具	描述
get_activity_feed	获取最近的活动信息
get_recent_games	获取最近的游戏详情
get_game_details	获取特定游戏的信息
get_season_stats	获取竞技赛季的统计数据
get_daily_challenge	获取每日挑战信息

分析

工具	描述
analyze_recent_games	分析性能趋势
get_performance_summary	获取全面的性能概述
get_strategy_recommendations	获取个性化的改进建议

API 监控

工具	描述
check_api_status	检查所有端点的可用性
get_endpoint_schema	获取特定端点的模式信息
list_available_endpoints	列出所有已知的端点
explore_endpoint	发现新的 API 端点

🔄 动态模式系统

服务器能够自动适应 API 的变化，其工作流程如下：

┌─────────────────────┐      ┌──────────────────┐
│   API 响应          │ ───▶ │  模式检测器      │
└─────────────────────┘      └────────┬─────────┘
                                      │
                                      ▼
┌─────────────────────┐      ┌──────────────────┐
│  模式注册表        │ ◀─── │  比较哈希值      │
│  (持久化)          │      └──────────────────┘
└─────────────────────┘
         │
         ▼
┌─────────────────────┐
│  动态响应          │ ───▶ 可供大语言模型使用
│  包含模式信息      │
└─────────────────────┘

工作原理

1. 每日监控：服务器每 24 小时检查所有已知的端点。
2. 模式检测：分析响应结构、字段类型和嵌套关系。
3. 变更检测：计算模式哈希值以检测修改。
4. 持久化：模式信息会被缓存到磁盘，重启后仍然保留。
5. 动态访问：工具返回包含模式信息的数据，供大语言模型使用。

示例：探索未知端点

用户："你能探索 /v3/some-new-endpoint API 吗？"

Claude 使用 explore_endpoint 工具：
{
  "success": true,
  "discovered_fields": ["id", "name", "data", "timestamp"],
  "schema_description": "端点：/v3/some-new-endpoint\n字段：\n  - id: 字符串\n  - name: 字符串\n  - data: 对象\n  - timestamp: 日期时间"
}

🏭 生产部署

服务器以预构建的 Docker 镜像形式提供：nyxiumyuuki/geoguessr-mcp:latest

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

适用于已安装 nginx-proxy-manager 的 VPS 部署：

# 在 VPS 上克隆仓库
git clone https://github.com/NyxiumYuuki/GeoGuessrMCP.git
cd GeoGuessrMCP

# 配置环境
cp .env.example .env
# 使用您的设置编辑 .env 文件：
# - GEOGUESSR_NCFA_COOKIE（用于访问 GeoGuessr API）
# - MCP_AUTH_ENABLED=true（可选，用于 MCP 服务器安全）
# - MCP_API_KEYS（如果启用身份验证）

# 运行部署脚本
./scripts/deploy.sh

方法 2：手动使用 Docker Compose 部署

开发/测试环境设置

# 使用 docker-compose.yml（开发环境）
docker compose up -d

使用 nginx-proxy-manager 的生产环境设置

# 使用 docker-compose.prod.yml（生产环境）
docker compose -f docker-compose.prod.yml up -d

在 nginx-proxy-manager 中配置 SSL：

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

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

方法 3：直接使用 Docker 运行

如果您不想使用 Docker Compose，可以按以下步骤操作：

# 拉取镜像
docker pull nyxiumyuuki/geoguessr-mcp:latest

# 创建模式缓存卷
docker volume create geoguessr-schemas

# 运行容器（无身份验证）
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

# 启用 MCP 身份验证运行
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

环境变量

变量	默认值	描述
GEOGUESSR_NCFA_COOKIE	-	GeoGuessr API 身份验证 Cookie
MCP_AUTH_ENABLED	false	启用 MCP 服务器身份验证
MCP_API_KEYS	-	用于 MCP 访问的逗号分隔的 API 密钥
MCP_PORT	8000	服务器端口
MCP_TRANSPORT	streamable-http	MCP 传输协议
MONITORING_ENABLED	true	启用 API 监控
MONITORING_INTERVAL_HOURS	24	监控检查间隔（每 24 小时运行一次）
SCHEMA_CACHE_DIR	/app/data/schemas	模式持久化目录
LOG_LEVEL	INFO	日志详细程度

🧪 开发

本地开发

# 创建虚拟环境
python -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements-dev.txt

# 运行测试
pytest -v

# 本地运行服务器
python -m geoguessr_mcp.main

项目结构

geoguessr-mcp/
├── src/geoguessr_mcp/
│   ├── api/              # API 客户端和端点
│   ├── auth/             # 身份验证
│   ├── models/           # 数据模型
│   ├── monitoring/       # 模式检测与监控
│   ├── services/         # 业务逻辑
│   ├── tools/            # MCP 工具定义
│   ├── config.py         # 配置文件
│   └── main.py           # 入口点
├── tests/
│   ├── unit/             # 单元测试
│   └── integration/      # 集成测试
├── nginx/                # 生产环境 nginx 配置
├── docker-compose.yml    # 开发环境部署
├── docker-compose.prod.yml # 生产环境部署
└── Dockerfile

🤝 贡献

欢迎贡献代码！请按以下步骤操作：

1. 分叉仓库
2. 创建功能分支
3. 为新功能添加测试
4. 提交拉取请求

📝 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

⚠️ 免责声明

本项目使用非官方的 GeoGuessr API，该 API 可能会在未通知的情况下发生变化。动态模式系统有助于缓解这一问题，但如果 GeoGuessr 对 API 进行重大更改，某些功能可能会失效。

本项目与 GeoGuessr AB 没有关联。