Content
# 🎫 damai-mcp
[](https://pypi.org/project/damai-mcp/)
[]()
[]()
[](https://modelcontextprotocol.io)
> Android device automation MCP — Let your AI directly control your phone/emulator to grab tickets from Damai, Maoyan, or FlyZoo.
Popular events (¥921 + 0.5 seconds to grab) are extremely competitive, making manual grabbing almost impossible. This project uses the [Model Context Protocol](https://modelcontextprotocol.io) to encapsulate ADB operations into over 30 tools, allowing Claude Code, Cursor, or custom Agents to operate the Damai app like a human, with a key path that is 200-500 ms faster than manual grabbing.
## ✨ Core Features
| | |
|---|---|
| 🪜 **4-layer architecture** | L1 device management / L2 atomic operations / L3 semantic queries / L4 business orchestration |
| 🚀 **Zero additional binary dependencies** | Reuses local `adb` (included with Lightning, MuMu, and SDK) |
| 🔌 **Standard MCP protocol** | Directly connects to Claude Code, Cursor, Cline, or Continue |
| 🧠 **Damai-specific** | `damai_grab()` provides a one-line call to complete "waiting for tickets → grabbing tickets → selecting people → submitting" |
| 📸 **Automatic screenshot archiving** | Automatically saves screenshots to `damai_shots/` in case of failure |
| ⏱️ **Millisecond-level waiting** | Uses `asyncio` for high-precision sleep, minimizing waste during ticket opening |
## 🚀 Get Started in 30 Seconds
### 1. Installation
```bash
pip install damai-mcp
```
### 2. Prepare Your Device (choose one)
| Device Type | ADB Port | Advantages |
|---|---|---|
| Lightning Emulator 9 | 127.0.0.1:5555 | Stable, multiple instances, free |
| MuMu Emulator | 127.0.0.1:7555 | Good performance |
| Physical Device (USB) | Auto-detect | Most realistic |
Ensure the Damai app is installed and logged in after launching.
### 3. Verify Connection
```bash
damai-mcp list-devices
# adb: C:\Program Files\LDPlayer\adb.exe
# 127.0.0.1:5555 device HUAWEI Pura 70 Pro 1080x2400 EMU
```
### 4. Start MCP Server (for Claude Code/Cursor)
```bash
damai-mcp serve
```
Add the following to Claude Code's `~/.claude/settings.json`:
```json
{
"mcpServers": {
"damai": {
"command": "damai-mcp",
"args": ["serve"]
}
}
}
```
Restart Claude Code, and the dialogue will show 30+ `damai__*` tools.
### 5. Let AI Grab Tickets for You
> "Use device 127.0.0.1:5555 to grab item 1063631004645, second price, Yang Anqi's ticket, opening at 17:21"
AI will automatically orchestrate:
```
list_devices → damai_check_login → damai_open_concert
↓ wait for tickets
damai_grab → save failed screenshots to damai_shots/grab_fail_xxx.png
```
## 📐 Architecture (4-layer tooling)
```
┌─────────────────────────────────────────────────────────┐
│ L4 Business Orchestration damai_grab, damai_grab_multi, damai_pay │ ← AI directly uses
├─────────────────────────────────────────────────────────┤
│ L3 Semantic Queries find_text, find_resource_id, find_xpath, │ ← uses semantic operations
│ wait_for_element, dump_ui │ on UI instead of coordinates
├─────────────────────────────────────────────────────────┤
│ L2 Atomic Operations tap, swipe, input_text, press_key, │ ← used for debugging
│ screenshot, scroll, long_press │
├─────────────────────────────────────────────────────────┤
│ L1 Device Management list_devices, connect_device, │ ← the beginning of everything
│ device_info, disconnect_device │
└─────────────────────────────────────────────────────────┘
```
**Core Principle**: AI should use L3 semantic tools, not L2 coordinate tools. When Damai updates, coordinates may become invalid, but "Purchase Now" will always be there.
## 🛠️ Direct Invocation (without MCP)
```python
import asyncio
from damai_mcp.damai.actions import damai_grab
async def main():
result = await damai_grab(
device_id="127.0.0.1:5555",
item_id="1063631004645",
price_index=2,
viewer_names=["Yang Anqi"],
open_time="2026-07-09 17:21:00",
preheat_seconds=30,
)
print(result)
asyncio.run(main())
```
Or via command line:
```bash
python examples/grab_one_ticket.py \
--device 127.0.0.1:5555 \
--item 1063631004645 \
--price 2 \
--viewer "Yang Anqi" \
--open "2026-07-09 17:21:00"
```
## 🧰 Practical Examples
### Grab One Ticket (single device)
See [`examples/grab_one_ticket.py`](examples/grab_one_ticket.py).
### Multi-account concurrency (5 emulators)
```bash
python examples/multi_devices.py \
--item 1063631004645 \
--price 2 \
--devices 127.0.0.1:5555 127.0.0.1:5557 127.0.0.1:5559 \
--viewers Yang Anqi Zhang San Li Si \
--open "2026-07-09 17:21:00"
```
### Update selectors when Damai updates
```bash
python examples/probe_selectors.py --device 127.0.0.1:5555
# outputs all clickable elements, updates damai_mcp/damai/selectors.py
```
## 🧪 Development
```bash
git clone https://github.com/your-org/damai-mcp
cd damai-mcp
pip install -e ".[dev]"
# testing (no physical device/emulator needed)
pytest
# linting + type checking
ruff check src tests
mypy src
# run example
python examples/grab_one_ticket.py --device 127.0.0.1:5555 --item TEST
```
## ⚠️ Compliance and Disclaimer
This project is for **learning and researching automation testing techniques** only. Please comply with:
1. Damai, Maoyan, and FlyZoo's user agreements
2. Chinese laws and regulations, including "Anti-Unfair Competition Law" and "Consumer Rights Protection Law"
3. Manually complete payment within 15 minutes of order generation
The author is not responsible for any account bans, legal disputes, or economic losses resulting from using this project.
## 🤝 Contributions
PRs are welcome! Especially:
- Maoyan/FlyZoo L4 business encapsulation (currently only Damai is implemented)
- Slider CAPTCHA automatic recognition (OpenCV/ddd docr/captcha platform)
- Record-replay workflow (allowing you to "record once and run automatically next time")
- New emulator support (Nightly/ Xiaoyao/BlueStacks)
## 📜 License
MIT — see [LICENSE](LICENSE).
