# QiyueAstro MCP Server 🎴☯️

MCP (Model Context Protocol) server for **Eastern & Western divination** — tarot, Lenormand, I Ching, Meihua, Qi Men, BaZi, Zi Wei Dou Shu, Xiao Liu Ren and Da Liu Ren.

Works with **Claude Desktop, Cursor, OpenClaw, Zed and any MCP client**. No API key, no signup — data comes from the free [QiyueAstro](https://qiyueastro.com) public API.

## ✨ Tools

| Tool | Description |
|---|---|
| `draw_tarot` | Draw tarot cards — 13 spreads (single, three-card, celtic-cross, yes-or-no, love…) or N cards |
| `browse_tarot` | Browse the 78-card Rider-Waite deck, card details by id |
| `list_tarot_spreads` | List all available tarot spreads |
| `draw_lenormand` | Draw Lenormand cards — 8 spreads (three, relationship, decision, nine-card grid, grand-tableau…) |
| `browse_lenormand` | Browse the 36-card Lenormand deck |
| `cast_iching` | I Ching hexagram casting (coins / time / numbers), moving lines + changed hexagram |
| `get_hexagram` | Look up any of the 64 hexagrams (id or binary) |
| `cast_meihua` | Meihua Yishu casting (time / numbers) with Ti/Yong analysis |
| `cast_qimen` | Qi Men Dun Jia chart layout |
| `bazi_chart` | BaZi (Four Pillars) chart — pillars, WuXing counts, DaYun |
| `ziwei_chart` | Zi Wei Dou Shu chart — 12 palaces, major stars, brightness |
| `cast_xiaoliuren` | Xiao Liu Ren quick divination (Da An, Liu Lian, Su Xi…) |
| `cast_liuren` | Da Liu Ren lesson casting — four lessons, three transmissions |

## 🚀 Install

### Claude Desktop

```json
// claude_desktop_config.json
{
  "mcpServers": {
    "qiyue": {
      "command": "npx",
      "args": ["-y", "github:BloodymaryGG/qiyue-mcp"]
    }
  }
}
```

### Cursor

Settings → MCP → Add new server:

```
Name: qiyue
Type: command
Command: npx -y github:BloodymaryGG/qiyue-mcp
```

### OpenClaw

```bash
openclaw mcp add qiyue -- npx -y github:BloodymaryGG/qiyue-mcp
```

### Manual (from source)

```bash
git clone https://github.com/BloodymaryGG/qiyue-mcp
cd qiyue-mcp
npm install
node index.mjs   # stdio MCP server
```

### Test without a client

```bash
npm install
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node index.mjs
```

## 🧩 Example prompts

- "Draw a three-card tarot spread about my career"
- "Cast the I Ching — should I accept the job offer?"
- "What does The Tower card mean?"
- "Give me my BaZi chart for 1998-06-15 12:00, male"
- "小六壬看一下今天运势"

## 🌙 About QiyueAstro

[QiyueAstro (栖月)](https://qiyueastro.com) — a full divination platform with **14 modules**, AI-powered readings in **9 languages**, free daily credits, and shareable reading cards. The MCP server above is a thin wrapper over its free public API.

## 📄 License

MIT. Card art is public-domain Rider-Waite-Smith line art.

---

Built with ❤️ by [BloodymaryGG](https://github.com/BloodymaryGG) · [qiyueastro.com](https://qiyueastro.com)