星穹铁道抽卡记录 MCP

用 Python + FastMCP 读取《崩坏：星穹铁道》账号跃迁（抽卡）记录，供 Cursor Agent 同步、查询与统计。

它做什么

保存抽卡 API 链接（含临时 authkey），或从本机游戏 webCaches 自动提取
调用官方 getGachaLog 分页拉取记录到本地 data/
在 Cursor 里用 tools 查记录、看垫数 / 五星

不会索要账号密码；authkey 大约 24 小时过期，过期后需重新进游戏打开跃迁记录。

环境准备

cd E:\code\mcpTraining
py -3.10 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

在 Cursor 中接入

见 docs/cursor-setup.md。
如何获取抽卡链接见 docs/get-gacha-url.md。

典型用法（对 Agent 说）

「用游戏缓存检测崩铁抽卡链接」→ detect_gacha_url_from_game_cache
「同步抽卡记录」→ sync_gacha_logs
「角色池现在垫了多少、最近五星是谁」→ gacha_stats / list_gacha_logs

本地网页看板

同步记录后，可启动本地网页查看统计（分池垫数、品阶分布、五星历程）：

.\.venv\Scripts\Activate.ps1
starrail-gacha-web
# 或: python -m starrail_gacha_mcp.webapp

浏览器会打开 http://127.0.0.1:8765/。加 --no-open 可只启动服务；--port 9000 可改端口。

在 Cursor 里也可直接让 Agent 调用 open_gacha_dashboard（会自动开浏览器）。

边改边看（开发模式）

调 web/ 排版时用开发模式：保存文件后浏览器自动刷新。

starrail-gacha-web --dev
# 或让 Agent: open_gacha_dashboard(dev=True)

停止后台看板：starrail-gacha-web --stop 或 MCP stop_gacha_dashboard。

项目结构

src/starrail_gacha_mcp/
  server.py      # MCP 入口与 tools
  webapp.py      # 本地网页服务
  auth.py        # URL 解析 / 游戏缓存扫描
  client.py      # 官方 API 分页
  store.py       # 本地 JSON
  stats.py       # 统计与垫数
web/             # 看板静态页（HTML/CSS/JS）
data/            # auth.json、gacha_logs.json（已 gitignore）

卡池类型

ID	名称
1	常驻跃迁
2	新手跃迁
11	角色活动跃迁
12	光锥活动跃迁

说明

官方接口通常只保留约近半年记录，不是无限全历史。
Windows 下自动检测最省事；其它系统可用 set_gacha_url 粘贴链接。
本项目仅供学习与个人查询，请遵守游戏与平台服务条款。

starrail-gacha