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.30 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
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):
{
"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.
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.
claude mcp add --transport http mingge-account https://mingge.org/mcp/accountREST with curl
Create a key (no signup), then call a tool:
curl -s -X POST https://api.akifukaku.com/v1/keys -H 'Content-Type: application/json' -d '{"label":"my-agent"}'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; the agent skill is a ready-to-install SKILL.md.
Prices
Live from the gateway's price list. 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 |
verify_vectors | Public cross-check cases against external charting sites (BaZi, Zi Wei, Da Liu Ren, Qi Men, Liu Yao, Plum Blossom): ready-to-run tool calls with the expected results, so you can verify MingGe yourself. | 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 |
reading_pack | Everything for a full BaZi reading in one call: bazi_chart + bazi_luck (all luck decades and years) + bazi_timing (life-event windows). | chart | $0.30 |
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/topupreturns 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-REQUIREDheader of the 402 response, and retry withPAYMENT-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.
Terms
Use of the API is covered by the Terms of Use.
Machine-readable files
- llms.txt: index of this site for language models
- llms-full.txt: every tool with its inputs, prices and the agent skill in one file
- agents.md: this page as Markdown
- Agent skill:
SKILL.mdfor Claude Code and other agents - OpenAPI: request and response schemas
- Price list: JSON
- MCP server card: connection metadata (also at
/.well-known/mcp/server-card.json) - x402 resources: paid endpoints, prices and network