mihoyo-mcp
This server lets MCP clients interact with miHoYo accounts (Miyoushe CN) to manage logins, discover accounts/roles, fetch real-time game notes, and get deduplicated stamina alerts.
QR login (Miyoushe): start a login session and poll until confirmed; credentials are stored encrypted inside the server and never exposed.
Account management: list logged-in accounts and their game UIDs, or refresh/re-discover roles for an account.
Star Rail daily note: see Trailblaze Power (including reserve), daily training, simulated universe points, and expeditions.
Genshin Impact daily note: see resin, realm currency, commissions, and expeditions.
Zenless Zone Zero daily note: see battery charge, activity/engagement, and video store status.
Alert checking:
starrail_check_alertsreturns only noteworthy changes (stamina threshold, expeditions/daily training completion) with cross-poll dedup, letting a scheduler decide when to notify users.
Provides miHoYo account integration via QR code login, multi-account and game role discovery, and real-time daily note retrieval for Star Rail, Genshin Impact, and Zenless Zone Zero, including stamina/resin/battery, expeditions, and alert checks with deduplication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mihoyo-mcp Check my Star Rail daily note and stamina alerts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 APIRelated 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 | ✅ |
Genshin Impact real-time note | ✅ |
Zenless Zone Zero real-time note | ✅ |
Star Rail alert check (dedup across polls) | ✅ |
HoYoLAB login | ⏳ Not integrated (see roadmap) |
Tool overview
Tool | Description |
| Creates a QR login session and returns |
| Polls the QR scan status: |
| Number of logged-in accounts and pending login sessions |
| Lists accounts and their game characters (uid), without any credentials |
| Re-discovers the game characters under an account |
| Trailblaze Power (with surplus), Daily Training, Simulated Universe, assignments |
| Resin, Realm currency, Daily Commissions, expeditions |
| Battery, Activity, and Video Store, etc. |
| 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, usingauth_/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 serverClient 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 |
|
| Data directory (accounts / credentials / alert states) |
| Auto-generated | Credential encryption key; in production, prefer putting it into a secret store |
|
| Default stamina threshold for |
|
| 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)
auth_start_qr_login("miyoushe")→ send the QR code fromqr_png_base64(orlogin_url) to the userThe user scans with the 米游社 App and confirms on their phone
auth_poll_qr_login(session_id)polls until it returnsconfirmedThe 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 anaccount_idlikemiyoushe:123456
Roadmap
Ordered by consumer needs (nahida-bot #52 etc.):
✅ Account / Auth — MiYoShe QR login, multi-account, character
✅ Daily Note + checks — Star Rail / Genshin / ZZZ daily notes,
check_values⏳ HoYoLAB login — email/password (already supported by genshin.py) or OS QR scan (endpoint to be verified/scannable)
Check-in / redemption codes (
check_in/codes.list/codes.redeem)Profile / character showcase (Enka, image panel query)
Game data / Build / progression calculator (hakush.in / Yatta / Ambr)
Gacha import and stats
Renderer (optional image-card generation; the tool returns structured data plus a rendering service)
Referenced projects & license
Project | License | Role in this project |
MIT | Direct dependency: API wrapper, DS, cookie and QR flow | |
GPL-3.0 | Arc, Opt, tokens, does not borrow code | |
MIT | CN-server behavior reference (error handling, daily note field traps) | |
CC BY-NC 4.0 | Protocol dictionary, for verification only, no implementation reuse | |
Unspecified | Modern CN-server QR login reference |
This project is licensed under the MIT License.
Available Tools
9 toolsaccounts_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Your Gmail, Calendar, Drive, GitHub, Oura, wallet and confirmed profile facts in any MCP client.
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Unofficial MCP server for Goofish (Xianyu) deals, item details, seller stock, and Zhima Credit.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables 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.16170 PyPI3Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables 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
- FlicenseNot gradedqualityCmaintenanceEnables authenticated querying of QQ Zone profiles, posts, statistics, albums, and message boards through MCP tools, with cookie management and optional HTTP/SSE access.-
- AlicenseNot gradedqualityCmaintenanceEnables 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.1MIT