# MingGe API and MCP server for AI agents

MingGe (命格) is a deterministic Chinese metaphysics engine that AI agents can call: BaZi (Four Pillars), Zi Wei Dou Shu, Qi Zheng Si Yu (Seven Governors and Four Remainders), synastry, date selection, the Chinese almanac and six kinds of divination (Liu Yao, Plum Blossom, Qi Men Dun Jia, Da Liu Ren, Xiao Liu Ren, temple lots). Scores, verdicts and timing windows come from the same engine as mingge.org, so your agent relays results instead of guessing them.

Price: $0.005 to $0.15 per call, helper tools free. Pay with prepaid credits (card or USDC), per call with x402 (USDC on Base), or with a MingGe account. Repeat calls with identical input are free for 30 days.

Connect over MCP at `https://mingge.org/mcp` (API key or x402) or `https://mingge.org/mcp/account` (sign in with a MingGe account), or call REST at `https://api.akifukaku.com/v1/mingge/<tool>`. New API keys include $0.10 of trial credit.

## Connect in ten seconds

### Claude Code

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

No key yet? Run it without `--header`, ask Claude to call `create_api_key`, then add the server again with the key.

### Cursor

Add this to `~/.cursor/mcp.json` (or the project's `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "mingge": {
      "url": "https://mingge.org/mcp",
      "headers": {
        "Authorization": "Bearer <your API key>"
      }
    }
  }
}
```

### Any MCP client

Streamable HTTP at `https://mingge.org/mcp`. Send your API key as a bearer token, or connect without one and call `create_api_key` first; the trial credit covers a couple of charts.

```text
URL:        https://mingge.org/mcp
Transport:  Streamable HTTP
Auth:       Authorization: Bearer <API key>  (or x402 per call)
```

### Sign in with a MingGe account

Use `https://mingge.org/mcp/account`. The client opens the MingGe sign-in and consent page; afterwards `my_charts` lists your saved charts and every chart tool accepts `chart_id` in place of `birth`.

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

### REST with curl

Create a key (no signup), then call a tool:

```bash
curl -s -X POST https://api.akifukaku.com/v1/keys -H 'Content-Type: application/json' -d '{"label":"my-agent"}'
```

```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,"cityName":"Shanghai","tz":"Asia/Shanghai"},"gender":"female"}'
```

Request and response schemas for every tool are in the [OpenAPI document](https://api.akifukaku.com/openapi.json); the [agent skill](https://api.akifukaku.com/mingge/skill.md) is a ready-to-install `SKILL.md`.

## Prices

Live from the gateway's [price list](https://api.akifukaku.com/v1/pricing). Free tools still need an API key. Failed calls are not charged.

| Tool | What it returns | Unit | Price (USD) |
|---|---|---|---|
| `birth_form` | Turn what the user said about their birth (date, time, city, gender; solar or lunar) into the `birth` object the chart tools take, with longitude and time zone filled from the city. | call | Free |
| `list_options` | The school / rule options each tool accepts (Qi Men centre palace and hidden stems, Liu Ren month general and noble person, day boundary, true solar time…): groups, ids, defaults and what each means. | call | Free |
| `my_charts` | List the user's saved charts in MingGe (id, label, birth summary). | call | Free |
| `almanac_day` | Chinese almanac (黄历) for a date: day pillars, do / avoid, day officer, solar term, clash. | day | $0.005 |
| `bazi_pillars` | BaZi skeleton only (facts, no judgement): four pillars, hidden stems, ten gods, nayin, life stages, void branches, shensha, and the luck-pillar sequence. | chart | $0.01 |
| `calendar_convert` | Convert a date (and optional time): Gregorian, Chinese lunar and stem-branch pillars, the solar term it falls in with exact term times, and true solar time when longitude is given. | date | $0.01 |
| `lexicon` | Look up a Chinese metaphysics term, star, shensha or pattern: meaning, the condition under which it forms, its share of all charts, and the classical source text. | term | $0.01 |
| `ziwei_board` | Zi Wei Dou Shu board only (facts, no patterns): twelve palaces with stars, brightness, four transformations and decade-limit ranges. | chart | $0.01 |
| `cast_xiaoliuren` | Xiao Liu Ren (小六壬) quick reading for the moment of asking: month / day / hour palaces and the final palace. | cast | $0.02 |
| `draw_lingqian` | Draw a temple lot (灵签) — Guanyin, the Matchmaker (Yuelao) or Guan Di. | lot | $0.02 |
| `bazi_chart` | BaZi (Four Pillars) chart from birth data: pillars, hidden stems, ten gods, MingGe archetype (one of 55) and title, substance / volatility / rarity scores, structure verdict, favourable and unfavourable elements, shensha, the current luck decade with its score and reasons, and this year. | chart | $0.05 |
| `bazi_period` | MingGe's score and grounds for a given year, month or day of a BaZi chart (annual, monthly, daily fortune), with the solar-term month it reads. | period | $0.05 |
| `cast_liuren` | Da Liu Ren (大六壬) lesson for the moment of asking: four lessons, three transmissions, heavenly generals, lesson type. | cast | $0.05 |
| `cast_liuyao` | Liu Yao (六爻) divination for one question: six lines by coin toss (default), by time or given manually; original and changed hexagram, six relatives, use god. | cast | $0.05 |
| `cast_meihua` | Plum Blossom (梅花易数) divination for one question, from the moment or from two numbers: original / mutual / changed hexagrams, body and use. | cast | $0.05 |
| `cast_qimen` | Qi Men Dun Jia (奇门遁甲) chart for the moment of asking: nine palaces with doors, stars, deities and stems, patterns. | cast | $0.05 |
| `ziwei_chart` | Zi Wei Dou Shu natal chart from birth data: soul and body palaces, five-element bureau, twelve palaces with major / minor stars, brightness and four transformations, decade limits, and the patterns the chart forms with their share of all charts. | chart | $0.05 |
| `hepan` | Synastry (合盘) of two people's birth data for romance, business partnership, friendship or family: overall score and title, six dimension scores with their grounds, cross-chart interactions, cross shensha, ten-god matrix, Zi Wei cross transformations. | pair | $0.10 |
| `qizheng_transit` | Qi Zheng Si Yu transits at a moment (default now) against the natal chart: where each luminary is and what it activates. | moment | $0.10 |
| `zeri_pick` | Date selection (择日): usable days for an event (wedding, engagement, moving in, opening, signing, groundbreaking, travel, seeing a doctor) within a date range, with reasons, excluding days that clash with the person's chart. | range | $0.10 |
| `ziwei_limits` | Zi Wei Dou Shu limits for a year, month or day: decade, annual, monthly and daily palaces with flying four transformations and notes. | period | $0.10 |
| `bazi_luck` | The full BaZi luck curve: all eight luck decades with MingGe's score (with scale), tier and grounds, plus a score for every year. | chart | $0.15 |
| `bazi_timing` | Life-event timing from a BaZi chart: time windows by area (marriage, career, wealth, move, health, children, home, parents, peers) with grounds. | chart | $0.15 |
| `qizheng_chart` | Qi Zheng Si Yu (七政四余, Chinese sidereal astrology) natal chart: the eleven luminaries' mansions and degrees, degree lords, benefic and malefic roles, star patterns, life and body lords. | chart | $0.15 |

A connected MingGe account adds a monthly allowance, used before prepaid credits and not carried over: free account $0.20, member $1.50, Pro $4.00. Account tools such as `my_charts` are free and rate-limited.

## Three ways to pay

- Prepaid credits: `POST https://api.akifukaku.com/v1/credits/topup` returns a payment link to hand to a person (card or USDC). Top-ups: $5, $20, $100.
- x402 per call: an agent holding a wallet pays each call in USDC on Base. Call without credentials, read the `PAYMENT-REQUIRED` header of the 402 response, and retry with `PAYMENT-SIGNATURE`.
- MingGe account: connect over OAuth at `https://mingge.org/mcp/account`; calls draw on the account's monthly allowance before any prepaid credits.

## Repeat calls are free

The same account calling the same tool with identical input is charged once per 30 days. A repeat returns `X-Replay: 1` over REST and `_meta.billing` over MCP. Casts whose result is random or depends on the moment of asking (coin tosses, lot draws, casts without an explicit date and time) are charged every time.

## Schools and options

Where traditions differ (the day boundary at 23:00 or midnight, true solar time, the Zi Wei leap month, the Qi Men plate method), every tool uses the same defaults as mingge.org. Choosing another school through an `options` parameter opens in the next release; results will then report the options they used.

## Privacy

Birth data is computed in memory only: it is not stored and not written to logs. See the [privacy policy](https://mingge.org/en/privacy).

## Terms

Use of the API is covered by the [Terms of Use](https://mingge.org/en/terms).

## Machine-readable files

- [llms.txt](https://mingge.org/llms.txt): index of this site for language models
- [llms-full.txt](https://mingge.org/llms-full.txt): every tool with its inputs, prices and the agent skill in one file
- [agents.md](https://mingge.org/agents.md): this page as Markdown
- [Agent skill](https://api.akifukaku.com/mingge/skill.md): `SKILL.md` for Claude Code and other agents
- [OpenAPI](https://api.akifukaku.com/openapi.json): request and response schemas
- [Price list](https://api.akifukaku.com/v1/pricing): JSON
- [MCP server card](https://mingge.org/mcp/server-card): connection metadata (also at `/.well-known/mcp/server-card.json`)
- [x402 resources](https://mingge.org/.well-known/x402): paid endpoints, prices and network

## 中文说明

命格是一套确定性的命理引擎，AI 智能体可以直接调用：八字、紫微斗数、七政四余、合盘、择日、黄历，以及六爻、梅花、奇门、大六壬、小六壬、灵签六种起课。分数、断辞与应期都出自与 mingge.org 同一个引擎。

接法：MCP 地址 `https://mingge.org/mcp`（API key 或 x402 现付），登录命格账号用 `https://mingge.org/mcp/account`；REST 地址 `https://api.akifukaku.com/v1/mingge/<tool>`。价目见上表，实时读取网关。

付法：预充值（银行卡或 USDC）、x402 按次现付（Base 上的 USDC）、命格账号每月赠送额度。同一账户同一工具同一入参 30 天内只收一次，失败不收费。

口径缺省与网站一致，可选流派参数下一版开放。生辰只在内存里算，不落库、不进日志。

Source: https://mingge.org/agents
