Skip to main content
Glama
mihoyo-mcp
by AI1379

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: douyin-mcp

Current capabilities

Capability

Status

MiYoShe QR code login (non-blocking start/poll)

✅ Reuses genshin.py's web QR flow

Multi-account + game character (uid) discovery

✅

Honkai: Star Rail real-time note

✅ starrail_daily_note

Genshin Impact real-time note

✅ genshin_daily_note

Zenless Zone Zero real-time note

✅ zzz_daily_note

Star Rail alert check (dedup across polls)

✅ starrail_check_alerts

HoYoLAB login

⏳ Not integrated (see roadmap)

Tool overview

Tool

Description

auth_start_qr_login(platform)

Creates a QR login session and returns login_url + base64 PNG QR code + session_id

auth_poll_qr_login(session_id)

Polls the QR scan status: pending / scanned / confirmed (automatically saves credentials and discovers game characters after confirmation)

auth_status()

Number of logged-in accounts and pending login sessions

accounts_list()

Lists accounts and their game characters (uid), without any credentials

accounts_refresh(account_id?)

Re-discovers the game characters under an account

starrail_daily_note(account_id?)

Trailblaze Power (with surplus), Daily Training, Simulated Universe, assignments

genshin_daily_note(account_id?)

Resin, Realm currency, Daily Commissions, expeditions

zzz_daily_note(account_id?)

Battery, Activity, and Video Store, etc.

starrail_check_alerts(account_id?, stamina_threshold=200)

Returns only "changes worth telling"; empty result = stay silent

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)

Variable

Default

Description

MIHOYO_MCP_DATA_DIR

~/.mihoyo-mcp

Data directory (accounts / credentials / alert states)

MIHOYO_MCP_FERNET_KEY

Auto-generated

Credential encryption key; in production, prefer putting it into a secret store

MIHOYO_MCP_STAMINA_THRESHOLD

200

Default stamina threshold for starrail_check_alerts

MIHOYO_MCP_LOG_LEVEL

INFO

Log level (logs go to stderr; stdout is reserved for the MCP protocol)

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

Project

License

Role in this project

seriaati/genshin.py

MIT

Direct dependency: API wrapper, DS, cookie and QR flow

seriaati / firefly-buddy

GPL-3.0

Arc, Opt, tokens, does not borrow code

Ljzd-PRO / nonebot-plugin-mystool

MIT

CN-server behavior reference (error handling, daily note field traps)

UIGF-org/mihoyo-api-collect

CC BY-NC 4.0

Protocol dictionary, for verification only, no implementation reuse

Marchen-orz/MiyoQian

Unspecified

Modern CN-server QR login reference

This project is licensed under the MIT License.

Available Tools

9 tools
accounts_listA

List logged-in miHoYo accounts with their game roles (uid per game). No credentials are ever included.

Inputs: no named parameters.

accounts_refreshA

Re-discover game roles (uids) for an account from miHoYo. Pass account_id, or omit it when only one account is logged in.

Inputs: account_id.

auth_poll_qr_loginA

Poll a QR login session started by auth_start_qr_login. Returns status pending/scanned/confirmed; on confirmed the account is stored and returned (cookies stay inside the server).

Inputs: session_id (required).

auth_start_qr_loginA

Start a Miyoushe QR login. Returns a login URL, a base64 PNG QR code and a session_id. Show the QR to the user (they scan it with the Miyoushe app), then call auth_poll_qr_login.

Inputs: platform.

auth_statusA

Overview of logged-in accounts and pending login sessions.

Inputs: no named parameters.

genshin_daily_noteA

Genshin Impact real-time note: resin, realm currency, commissions and expeditions. account_id from accounts_list; omit when only one account is logged in.

Inputs: account_id.

starrail_check_alertsA

Check a Star Rail note and return only noteworthy changes (stamina nearly full/full, expeditions complete, daily training complete), with cross-poll dedup — an alert fires once until the condition resets. Designed for scheduled polling: empty alerts means stay quiet. account_id from accounts_list; omit when only one account is logged in; stamina_threshold defaults to 200.

Inputs: account_id, stamina_threshold.

starrail_daily_noteA

Star Rail real-time note: stamina (trailblaze power), reserve stamina, daily training, weekly rogue points and expeditions. account_id from accounts_list; omit when only one account is logged in.

Inputs: account_id.

zzz_daily_noteA

Zenless Zone Zero real-time note: battery charge, engagement, video store. account_id from accounts_list; omit when only one account is logged in.

Inputs: account_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools have sharply distinct purposes: auth tools, account tools, and per-game note tools are clearly separated. However, auth_status and accounts_list both relate to logged-in accounts, and starrail_daily_note vs starrail_check_alerts could be confused if not read carefully.

    Naming Consistency4/5

    Names follow a consistent lower_snake_case, domain-prefixed pattern like auth_start_qr_login, accounts_refresh, and genshin_daily_note. The main deviation is that 'daily_note' is a noun rather than a verb phrase like 'get_daily_note', but the pattern remains predictable.

    Tool Count5/5

    Nine tools is a well-scoped size for this server: QR login lifecycle, account listing/refresh, and three per-game real-time note endpoints plus one alert helper. Each tool has a distinct role and none feels redundant or excessive.

    Completeness4/5

    The core workflow is covered: login, poll login, list accounts, refresh roles, and retrieve daily notes for all three supported games. Minor gaps exist such as no explicit logout/account removal and alert-polling only for Star Rail, but agents can work around these by using the existing notes tools.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables reading public Bilibili video information — keyword search, UP profiles and uploads, video details and parts, comments and replies, danmaku, subtitles, and frame snapshots — through an MCP interface, with optional Bilibili login for authenticated features such as comments and subtitles.
      16
      170 PyPI
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to log in to their own Douyin account via QR code, publish videos or image notes, and perform simple reads such as search, video details, comments, and user posts through a local MCP server.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables authenticated querying of QQ Zone profiles, posts, statistics, albums, and message boards through MCP tools, with cookie management and optional HTTP/SSE access.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables standard MCP clients to search Bilibili videos, read subtitles and comments, extract video frames, manage favorites and follow relationships, access personalized feeds and history, and send or read private messages. It also supports QR login, configurable daily browsing reports, and profile, emoji, and dynamic operations.
      1
      MIT