Bazi MCP (@lhk714/bazi-mcp)

Deterministic, high-precision Four Pillars of Destiny (八字排盘) Model Context Protocol (MCP) server powered by a physical dual-axis astronomical time engine and global geographic database (7,329 cities across 227 countries).

中文文档 (Chinese) | English

🌟 Overview

@lhk714/bazi-mcp provides a production-grade, offline-first MCP server for Large Language Models (Claude, Cursor, Antigravity, ChatGPT, DeepSeek) to perform rigorous Chinese Four Pillars of Destiny (八字) calculations for anyone, anywhere on Earth, across 1800–2100.

It is published on the NPM registry and can be run instantly without manual installation or local compilation.

Birth Wall Clock Time + IANA Timezone (e.g. 1990-06-15 20:00 America/Los_Angeles)
                          │
            ┌─────────────┴─────────────┐
            ▼                           ▼
      【Axis A: UTC Instant】     【Axis B: Local True Solar Time】
   UTC: 1990-06-16 03:00:00Z    Wall + Longitude + Meeus EoT - DST
      Beijing: 1990-06-16 11:00   Local Solar: 1990-06-15 18:49
            │                           │
            ├──────────────┐            ├──────────────┐
            ▼              ▼            ▼              ▼
       【Year Pillar】 【Month Pillar】 【Day Pillar】 【Hour Pillar】
          庚午            壬午          辛亥            丁酉
            │
            ▼
      【Da Yun (起运)】

Related MCP server: BaZi (Eight Characters) Calculator

🔮 What this server will not tell you

It calculates; it does not infer. 身强/身弱, 喜用神 and 格局 are weighings, and no source supplies the weights they need — every published figure either contradicts the next or comes from closed software. A scored verdict here would rest on numbers invented in this repository, however carefully the method were named. v3.1.0 shipped one; v4.0.0 removed it.

What you get instead is strengthFactors, a zero-weight ledger: 月令 relation and 旺相休囚死, per-branch roots with their qi level and any 禄/刃/长生/墓库根 tag, and stem-support direction. Every entry is a table lookup. Weigh them with your own school's rules, or with a 命理 knowledge base — the facts are all here, and they are the part that can be got right.

Every table that sits on a school dispute is a named input, and strengthFactors.conventions echoes back the one in force, the ones not used, and the output fields that would change:

monthOrderSchool: "earth_rules_final_18_days" gives 土 the final 18 days before the next 立 and leaves the days before them with the closing season (辰木 未火 戌金 丑水). Only 辰戌丑未 months can move; the other eight have the season's element as their main qi already. The distance it turns on ships with the result as monthOrder.daysToNextJie, and the element it resolved to as monthOrder.rulingElement, so the verdict is reproducible from the output.

阴刃 gets no default. Three readings are in print — 帝旺 (乙寅 丁巳 己巳 辛申 癸亥), 冠带/禄前一位 (乙辰 丁未 己未 辛戌 癸丑), and no 阴刃 at all — and nothing here breaks the tie, so the caller names one or gets 阳刃 alone. For a yin day master the 十二长生 fork moves every branch: 辛 in 巳 is 死 under the default 渊海子平 convention, 长生 under 滴天髓's 阴阳同生同死. Pass twelveStageSchool: "yin_follows_yang" to take the second one; the school in force is echoed back in conventions.twelveStage. Yang day masters are identical under both. 禄 and 刃 are read from the 十干禄 and 阳刃 tables and do not move with the fork — only 长生 does.

Absent entirely when the birth hour is unknown.

🚀 Quickstart: Run via NPM

You can run @lhk714/bazi-mcp directly from NPM using Bun or Node.js (NPX) with zero local repository setup.

Option 1: Instant execution with Bun (bunx)

bunx @lhk714/bazi-mcp

Option 2: Instant execution with Node.js (npx)

npx -y @lhk714/bazi-mcp@latest

Option 3: Global Installation

# Install globally via Bun
bun add -g @lhk714/bazi-mcp

# Or install globally via NPM
npm install -g @lhk714/bazi-mcp@latest

# Then run anywhere:
bazi-mcp

⚙️ MCP Client Configuration

Add @lhk714/bazi-mcp to your MCP client config (e.g. Claude Desktop, Cursor, Cline, Roo Code, Antigravity):

Using Bun (bunx):

{
  "mcpServers": {
    "bazi": {
      "command": "bunx",
      "args": ["@lhk714/bazi-mcp@latest"]
    }
  }
}

Using Node.js (npx):

{
  "mcpServers": {
    "bazi": {
      "command": "npx",
      "args": ["-y", "@lhk714/bazi-mcp@latest"]
    }
  }
}

🛠️ MCP Tools Reference

1. calculate_bazi

Calculates Four Pillars, Day Master, Da Yun (Major Luck Cycles labeled with nominal age 虚岁), Stem & Branch Interactions (天干五合、地支刑冲合会), and Diagnostic Metadata.

* Provide either solarDate or lunarDate.
** Provide either clockTime, shichen, or timeUnknown: true.

diagnostics.locationSource reports whether the location was "resolved" from the global city database, "caller_supplied" via explicit coordinates, or "mixed" (place coordinates paired with a caller-supplied custom timezone).

2. lookup_location

Resolves city names to coordinates, administrative regions, and official IANA timezone identifiers across 7,329 global cities in 227 countries.

Ambiguous names are refused, never guessed — including same-name cities that share a timezone. Columbus OH and Columbus GA are both America/New_York but sit 2° of longitude apart: 8 minutes of true solar time, enough to cross a 時辰 boundary. A refusal returns { code, message, matched, candidates }, where matched is the true hit count so a capped list never reads as exhaustive, and candidates carry identifying fields only (no population — that is a ranking prior, not an identifier).

Unknown birth time

timeUnknown: true nulls the hour pillar, but the other three and the 大運 sequence are not derived from a substituted time.

• The year, month and day pillars are evaluated at both ends of the local day. Where they agree, they are reported plainly. Where a solar term falls inside the day and they disagree, both land in diagnostics.pillarCandidates with a warning — no side is silently chosen.

• The 早子時 hour (23:00–24:00) rolls the day pillar on every date, not just special ones. That uncertainty is asymmetric — 23 of 24 hours give one value — so it is reported asymmetrically: pillars.day holds the majority value and diagnostics.dayPillarAlternative names the other with its window. A 50/50 candidate pair would misstate how much is actually unknown.

• daYun.startDate becomes a date range. Measured on 2024-02-04 in Beijing, the 起運 date swings across three months over one unknown day; a to-the-second answer there is a fabrication.

🧪 Verification & Benchmark Matrix

@lhk714/bazi-mcp is verified against 117 rigorous test cases (100% passing):

1. Astro-Databank Rodden Rating AA Hospital Birth Certificates:

   • Donald Trump: 1946-06-14 10:54 EDT (New York, NY) ➔ 丙戌 甲午 己未 己巳

   • Barack Obama: 1961-08-04 19:24 HST (Honolulu, HI) ➔ 辛丑 乙未 己巳 癸酉

   • Bill Gates: 1955-10-28 22:00 PST (Seattle, WA) ➔ 乙未 丙戌 壬戌 辛亥

   • Steve Jobs: 1955-02-24 19:15 PST (San Francisco, CA) ➔ 乙未 戊寅 丙辰 丁酉 (True Solar correction shifts 19:15 to 18:52 酉 hour)

   • Albert Einstein: 1879-03-14 11:30 (Ulm, Germany) ➔ 己卯 丁卯 丙申 甲午

2. Official Historical Archives & Canonical Metaphysics Records:

   • Chiang Kai-shek: 1887-10-31 12:00 (Zhejiang Fenghua - Qian Li Ming Gao) ➔ 丁亥 庚戌 己巳 庚午

   • Mao Zedong: 1893-12-26 辰时 (Hunan Shaoshan) ➔ 癸巳 甲子 丁酉 甲辰

   • Zhou Enlai: 1898-03-05 卯时 (Jiangsu Huaian) ➔ 戊戌 甲寅 丁卯 癸卯

   • Deng Xiaoping: 1904-08-22 申时 (Sichuan Guangan) ➔ 甲辰 壬申 戊子 庚申

   • Liang Qichao: 1873-02-23 丑时 (Guangdong Xinhui) ➔ 癸酉 甲寅 丙午 己丑

3. Global Multi-Region Suite (28 regions across 6 continents):

   • China (Kashgar extreme west, Harbin extreme east, Lhasa high-altitude, Sanya tropical, Hong Kong, Taipei).

   • Americas (New York, Los Angeles, Chicago, Phoenix no-DST, St. John's 30-min timezone, São Paulo, Buenos Aires).

   • Europe & Eurasia (London GMT/BST, Paris, Moscow, Vladivostok, Reykjavik UTC+0).

   • Asia & Middle East (Tokyo, Seoul, Singapore, New Delhi / Mumbai UTC+5:30, Dubai).

   • Oceania & Southern Hemisphere (Sydney reversed DST, Perth, Auckland).

   • Africa (Johannesburg, Cairo).

🔄 CI/CD & Automated NPM Publishing

The repository is equipped with automated GitHub Actions:

• Continuous Integration (ci.yml): Runs tests and builds on every push/PR to main.

• Automated NPM Release (publish.yml): Automatically tests, builds, and publishes @lhk714/bazi-mcp to NPM whenever a new release or tag (e.g. v1.0.0) is created.

📜 License

MIT License © 2026 Wesley Liu