金大哥 - geoguessrmcp MCP 详情

article

README

🚀 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 账户。

工作原理

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

设置示例

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"
会话完全独立！

添加新用户

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

编辑 .env 文件，将新的 API 密钥添加到 MCP_API_KEYS 中。
重启服务器：docker compose restart
将新的 API 密钥分享给用户。
用户使用 API 密钥配置其 Claude 桌面。
用户通过 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 响应          │ ───▶ │  模式检测器      │
└─────────────────────┘      └────────┬─────────┘
                                      │
                                      ▼
┌─────────────────────┐      ┌──────────────────┐
│  模式注册表        │ ◀─── │  比较哈希值      │
│  (持久化)          │      └──────────────────┘
└─────────────────────┘
         │
         ▼
┌─────────────────────┐
│  动态响应          │ ───▶ 可供大语言模型使用
│  包含模式信息      │
└─────────────────────┘

工作原理

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

示例：探索未知端点

用户："你能探索 /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

🤝 贡献

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

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

📝 许可证

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

⚠️ 免责声明

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

本项目与 GeoGuessr AB 没有关联。

geoguessrmcp

README

🚀 GeoGuessr MCP 服务器

📋 待办事项

✨ 主要特性

多用户支持

动态 API 监控

全面分析

轻松部署

🚀 快速开始

前提条件

1. 克隆并配置

2. 部署

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

4. 连接到 Claude

🔐 身份验证

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

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

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

选项 2：使用环境变量

选项 3：手动设置 Cookie

👥 多用户模式

工作原理

设置示例

添加新用户

📊 可用工具

身份验证

个人资料与统计信息

游戏与活动

分析

API 监控

🔄 动态模式系统

工作原理

示例：探索未知端点

🏭 生产部署

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

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

开发/测试环境设置

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

方法 3：直接使用 Docker 运行

环境变量

🧪 开发

本地开发

项目结构

🤝 贡献

📝 许可证

⚠️ 免责声明

运行方式说明

托管运行

本地运行 / 其它方式