Skip to main content
Glama
README.md
# MingGe MCP server — BaZi, Zi Wei Dou Shu, Qi Zheng Si Yu and divination for AI agents

MingGe ([mingge.org](https://mingge.org/agents)) is a deterministic engine for Chinese metaphysics, exposed as a remote MCP server and a REST API. Your agent gets structured, checkable results — charts, scores with their scale, verdicts with grounds, timing windows — and explains them to the user in their own language.

- **MCP (API key or x402):** `https://mingge.org/mcp`
- **MCP (sign in with a MingGe account, OAuth):** `https://mingge.org/mcp/account`
- **REST:** `https://api.akifukaku.com/v1/mingge/<tool>` · [OpenAPI](https://api.akifukaku.com/openapi.json) · [prices](https://api.akifukaku.com/v1/pricing)
- **Docs for agents:** [mingge.org/llms.txt](https://mingge.org/llms.txt) · [llms-full.txt](https://mingge.org/llms-full.txt) · [skill](skill/SKILL.md)

Pay per call, a few US cents: skeleton tools $0.01, judgement tools $0.05–0.15. Repeat calls with the same input within 30 days are free. No signup needed.

## Connect in ten seconds

Claude Code:

```bash
claude mcp add --transport http mingge https://mingge.org/mcp
```

Then ask your agent to call `create_api_key` (free, includes a small trial credit) and set the key as the server's bearer token:

```bash
claude mcp add --transport http mingge https://mingge.org/mcp --header "Authorization: Bearer $AKI_API_KEY"
```

Any MCP client (Cursor, Windsurf, VS Code, …):

```json
{
  "mcpServers": {
    "mingge": { "url": "https://mingge.org/mcp", "headers": { "Authorization": "Bearer YOUR_AKI_API_KEY" } }
  }
}
```

Have a MingGe account? Use `https://mingge.org/mcp/account` instead: the client opens a sign-in page, the account gets monthly API credits (more for members), and `my_charts` / `chart_id` use the user's saved charts.

REST, one line:

```bash
curl -s -X POST https://api.akifukaku.com/v1/mingge/bazi_chart \
  -H "Authorization: Bearer $AKI_API_KEY" -H 'Content-Type: application/json' \
  -d '{"birth":{"year":1990,"month":5,"day":1,"hour":14,"minute":30,"longitude":121.47,"tz":"Asia/Shanghai"},"gender":"female"}'
```

## Tools

| Layer | Tools |
|---|---|
| Free (key required) | `birth_form` (a sentence → birth data), `my_charts` (account), `get_pricing`, `get_balance`, `topup_link`, `create_api_key` |
| Skeleton (facts) | `bazi_pillars`, `ziwei_board`, `calendar_convert`, `almanac_day` |
| Judgement | `bazi_chart`, `bazi_luck`, `bazi_timing`, `bazi_period`, `ziwei_chart`, `ziwei_limits`, `qizheng_chart`, `qizheng_transit`, `hepan` (synastry), `zeri_pick` (date selection) |
| Divination | `cast_liuyao`, `cast_meihua`, `cast_qimen`, `cast_liuren`, `cast_xiaoliuren`, `draw_lingqian` |
| Reference | `lexicon` (terms, stars, patterns, classical sources) |

Live prices: [api.akifukaku.com/v1/pricing](https://api.akifukaku.com/v1/pricing). Every tool's MCP description also ends with its price.

## Paying

1. **API key + prepaid credits** — `POST https://api.akifukaku.com/v1/keys` (no signup); top up by card or USDC with `topup_link`.
2. **x402** — no account: retry the call with a `PAYMENT-SIGNATURE` header (USDC on Base) built from the 402's `PAYMENT-REQUIRED`. Manifest: [api.akifukaku.com/.well-known/x402](https://api.akifukaku.com/.well-known/x402).
3. **MingGe account** — OAuth at `https://mingge.org/mcp/account`; monthly credits included, then pay per call.

Failed calls are not charged.

## Rules for agents

- Every judgement comes from the engine. Relay it; never recompute a chart, change a verdict or invent numbers. Quote scores with their scale.
- Same input + same engine version → the same result, byte for byte (`engine_version` is in every response).
- Verdict text is in Chinese (`verdict_lang: "zh"`); translate it without changing the judgement.
- Cultural and reflective content, not medical, legal or financial advice.
- Birth data is computed in memory and never stored or logged.

Terms of use for the API: [mingge.org/terms#agent-api](https://mingge.org/terms#agent-api).

## This repository

Docs and metadata only; the server is hosted. [`server.json`](server.json) is the entry in the official MCP Registry (`org.mingge/mingge`). [`skill/SKILL.md`](skill/SKILL.md) is an Agent Skill you can drop into Claude Code or any agent that reads skills.

Operated by Aki Fukaku, Australia. Contact: support@mingge.org.