maimai DX MCP Server

A high-performance, lightweight, modular maimai DX Model Context Protocol (MCP) server built with Rust.

• 📖 Configuration & Deployment Guide (docs/CONFIG_GUIDE.md)

• 📦 Download Prebuilt Binaries (GitHub Releases)

• Drawing & business reference: Yuri-YuzuChaN/maimaiDX

• Python version archive: legacy branch

🌟 Core Features

• ⚡ Extreme Performance & Lightweight: Pure Rust implementation, millisecond-level cold start, idle memory usage below 15MB, no heavy external C library dependencies.

• 🎨 Pixel-Perfect Pure Rust Drawing Engine:

  • The drawing layout, art asset catalog format, and coordinate rendering logic of this project are a pure Rust migration and optimization of the absolute coordinate system from the open-source project Yuri-YuzuChaN/maimaiDX.

  • Built on image + ab_glyph and a rayon multi-threaded pipeline, rendering B50, single-song result cards, plate progress tables, and fortune images with strict 1:1 high-fidelity absolute coordinates.

• 🤖 Friendly to Weak & Small-Parameter Models:

  • Lenient parameter normalization: Automatically handles Chinese difficulty names ("紫/白/黄/红/绿"), float constant conversion, and fuzzy matching of song title aliases.

  • Crash-proof Chinese fallback: Returns structured, human-readable guidance when data is not found or the account is unbound, avoiding hallucinations or repeated call-stack echoes from small models.

• 🚀 Out-of-the-Box:

  • Dual-track image & text output: By default returns both standard MCP Image Content (Base64) and a local file persistence path, seamlessly integrating with various Bot message senders.

  • Zero-friction score lookup: After configuring global developer credentials, a one-click score image can be produced using only the QQ number from context.

Related MCP server: Claud-Ear

🛠️ MCP Tool Registry

All tools support optional parameters: qq (user QQ number), username (username), source ("divingfish" or "lxns"), output_format ("image", "text", "both").

⚙️ Environment Configuration

The server supports configuration via environment variables or a .env file:

# 水鱼查分网开发者 Token（配置后仅凭 QQ 号即可直接查分）
DIVINGFISH_DEVELOPER_TOKEN=your_divingfish_developer_token

# 落雪查分网开发者 Token（可选）
LXNS_DEVELOPER_TOKEN=your_lxns_token

# 静态资源根目录（默认 ./static 或 ../maimaiDX/static）
MAIMAI_STATIC_DIR=./static

# 本地数据与用户配置存储目录（默认 ./data）
MAIMAI_DATA_DIR=./data

# 生成图片临时保存目录（默认 ./output）
MAIMAI_OUTPUT_DIR=./output

📁 Static Asset Preparation & Directory Structure

1. Directory Structure

Place the static asset folder in the project root (or specify an absolute path via MAIMAI_STATIC_DIR):

static/
├── font/              # 字体文件 (ResourceHanRoundedCN-Bold.ttf 等)
├── data/              # 歌曲/别名/牌子数据缓存 (music_data.json 等)
└── mai/
    ├── pic/           # UI 边框、评级底图、段位图标
    ├── cover/         # 曲目封面 (以 song_id 命名)
    ├── plate/         # 姓名框与牌子背景
    ├── shougou/       # 称号底图
    └── plate_version/ # 各版本牌子标识

2. Static Assets

Download and extract the asset package:

• Cloudreve

• OneDrive

Note the absolute path of the static directory (i.e., MAIMAI_STATIC_DIR in the config). Please comply with the upstream art and font-related notices.

🚀 Installation & Running

1. Method A: Download Prebuilt Binary Directly (Recommended)

Download the archive (Windows / Linux) matching your system architecture from GitHub Releases, extract it, and use it directly.

2. Method B: Build from Source

cargo build --release

3. Local Testing of the MCP Server

It can be run via standard stdio:

./target/release/maimai-mcp

3. Integration with AstrBot / Claude Desktop

Add to the mcpServers configuration:

{
  "mcpServers": {
    "maimai": {
      "command": "/path/to/maimai-mcp",
      "env": {
        "MAIMAI_STATIC_DIR": "/path/to/static",
        "DIVINGFISH_CLIENT_ID": "your_divingfish_client_id",
        "DIVINGFISH_CLIENT_SECRET": "your_divingfish_client_secret"
      }
    }
  }
}

🙏 Credits & Attribution

This project has deeply referenced and reused the design and resource specifications of the following excellent open-source projects during development:

• Yuri-YuzuChaN/maimaiDX (MIT License):

  • The drawing rendering logic, UI element layout, absolute pixel coordinate system, and static asset directory structure of this project all originate from the exquisite design of that project.

  • Special thanks to all contributors of the maimaiDX project!

• Score lookup & data source ecosystem:

  • Thanks to DivingFish for providing the open score-lookup API and OAuth platform.

  • Thanks to LXNS for providing the open data interface and OAuth platform.

  • Thanks to Yuzuchan for providing the song alias database.

📜 License & Resource Rights Notice

• This code repository is open-sourced under the BSD 2-Clause License;

• The upstream reference project license is at LICENSE-UPSTREAM;

• Resource copyright notice: static and other art/font resources are not distributed with this code repository; their copyrights are governed by the asset package and official notices, and they are not covered by this open-source license. Users are responsible for ensuring the legality and compliance of their use of the assets, and for complying with the original authors' notices for each font and asset.

📄 Architecture & Design Decisions

• Domain Model Glossary (CONTEXT.md)

• Architecture Decision Records (docs/adr/)

• Development Implementation Guide (AGENTS.md)