mihoyo-mcp

A standalone miHoYo MCP server — targeting both MiYoShe (CN server) and HoYoLAB (global server), built on seriaati/genshin.py (MIT). Any MCP client (nahida-bot, Claude Desktop, Codex...) can use it directly.

Design boundaries

The MCP handles "how to talk to miHoYo"; the client handles "when to ask, and who to tell afterwards".

• Scheduling (cron), threshold policies, message push → the client (nahida-bot already has Scheduler / Channel)

• Login, credential storage, API calls, alert dedup → this service

• Credentials never leave the security boundary: Cookies stay inside the service for the whole time (Fernet encryption), the tool results only contain account_id, and no token ever appears in the Agent context

                ┌─────────────────────┐
                │     nahida-bot      │
                │  Cron / Scheduler   │
                │       │             │
                │       ▼             │
                │  MCP Client ───────────────┐
                │       ▼             │     │ MCP (stdio)
                │  QQ Channel         │     ▼
                └─────────────────────┘ ┌──────────────────┐
                                       │    mihoyo-mcp     │
                                       │ QR login          │
                                       │ credential vault  │
                                       │ daily notes       │
                                       │ alert dedup state │
                                       └────────┬──────────┘
                                                │
                                         genshin.py
                                                │
                                     米游社 / HoYoLAB API

Related MCP server: Xiaohongshu MCP Server

Current capabilities

Tool overview

account_id can be omitted when there is only one account.

About naming: the original design used dot-like names such as mihoyo.auth.start_qr_login, but the MCP spec (SEP-986) requires tool names to match ^[a-zA-Z0-9_-]{1,64}$. Dots make some clients refuse to load, so flat snake_case naming-ish, using auth_ / accounts_ / starrail_ prefixes as namespaces.

Why check_alerts is part of the MCP

The stamina threshold check (217 >= 200 && recovery <= 1800) does not need to burn LLM tokens, and announcing "the expedition is back" on every poll is unacceptable. The alert dedup state (armed/re-arm) is part of the MiYoShe integration state and naturally belongs to this service. The client's cron only needs:

starrail_check_alerts() → alerts == [] → 静默
                      → alerts != [] → 推送消息

Quick start

uv sync                       # 安装依赖
uv run pytest                 # 运行测试
uv run python scripts/smoke_stdio.py   # stdio 握手冒烟测试
uv run mihoyo-mcp             # 启动 stdio server

Client configuration example (Claude Desktop / any MCP client that supports stdio):

{
  "mcpServers": {
    "mihoyo": {
      "command": "uv",
      "args": ["run", "--directory", "D:/Projects/mihoyo-mcp", "mihoyo-mcp"]
    }
  }
}

Configuration (environment variables)

Data directory contents:

~/.mihoyo-mcp/
├── accounts.json     # 公开账号元数据（无秘密）
├── credentials.enc   # Fernet 加密的 Cookie/token 库
├── alert_state.json  # 告警去重状态
└── fernet.key        # 未设置环境变量时自动生成的 key（带告警日志）

Directory structure

src/mihoyo_mcp/
├── server.py          # MCPServer 装配 + stdio 入口
├── config.py          # 环境变量配置
├── context.py         # AppContext 单例装配
├── errors.py          # 领域错误（映射为 MCP tool error）
├── accounts/          # 账号模型 / 注册表 / 加密凭据库
├── auth/              # 扫码登录（start/poll 会话）
├── games/             # genshin.py 客户端工厂 + 便笺获取/归一化
├── alerts/            # 告警去重状态机（纯逻辑，可测）
└── tools/             # MCP 工具注册（auth / accounts / notes）

Login flow (MiYoShe)

1. auth_start_qr_login("miyoushe") → send the QR code from qr_png_base64 (or login_url) to the user

2. The user scans with the 米游社 App and confirms on their phone

3. auth_poll_qr_login(session_id) polls until it returns confirmed

4. The service internally stores the v2 cookies (account_id_v2 / account_mid_v2 / ltoken_v2 / cookie_token_v2…) and discovers the game characters; after that the Agent only sees an account_id like miyoushe:123456

Roadmap

Ordered by consumer needs (nahida-bot #52 etc.):

1. ✅ Account / Auth — MiYoShe QR login, multi-account, character

2. ✅ Daily Note + checks — Star Rail / Genshin / ZZZ daily notes, check_values

3. ⏳ HoYoLAB login — email/password (already supported by genshin.py) or OS QR scan (endpoint to be verified/scannable)

4. Check-in / redemption codes (check_in / codes.list / codes.redeem)

5. Profile / character showcase (Enka, image panel query)

6. Game data / Build / progression calculator (hakush.in / Yatta / Ambr)

7. Gacha import and stats

8. Renderer (optional image-card generation; the tool returns structured data plus a rendering service)

Referenced projects & license

This project is licensed under the MIT License.