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/account

REST 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.

ToolWhat it returnsUnitPrice (USD)
birth_formTurn 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.callFree
list_optionsThe 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.callFree
my_chartsList the user's saved charts in MingGe (id, label, birth summary).callFree
verify_vectorsPublic 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.callFree
almanac_dayChinese almanac (黄历) for a date: day pillars, do / avoid, day officer, solar term, clash.day$0.005
bazi_pillarsBaZi 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_convertConvert 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
lexiconLook 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_boardZi Wei Dou Shu board only (facts, no patterns): twelve palaces with stars, brightness, four transformations and decade-limit ranges.chart$0.01
cast_xiaoliurenXiao Liu Ren (小六壬) quick reading for the moment of asking: month / day / hour palaces and the final palace.cast$0.02
draw_lingqianDraw a temple lot (灵签) — Guanyin, the Matchmaker (Yuelao) or Guan Di.lot$0.02
bazi_chartBaZi (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_periodMingGe'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_liurenDa Liu Ren (大六壬) lesson for the moment of asking: four lessons, three transmissions, heavenly generals, lesson type.cast$0.05
cast_liuyaoLiu 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_meihuaPlum Blossom (梅花易数) divination for one question, from the moment or from two numbers: original / mutual / changed hexagrams, body and use.cast$0.05
cast_qimenQi Men Dun Jia (奇门遁甲) chart for the moment of asking: nine palaces with doors, stars, deities and stems, patterns.cast$0.05
ziwei_chartZi 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
hepanSynastry (合盘) 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_transitQi 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_pickDate 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_limitsZi 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_luckThe 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_timingLife-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_chartQi 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_packEverything 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/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.

Terms

Use of the API is covered by the Terms of Use.

Machine-readable files

中文说明

命格是一套确定性的命理引擎,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 天内只收一次,失败不收费。

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