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 any era.

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

🚀 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

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

# Then run anywhere:
bazi-mcp

🔌 MCP Client Configuration

Add @lhk714/bazi-mcp to your MCP client configuration file (e.g., claude_desktop_config.json, Cursor Settings, or Antigravity):

1. Claude Desktop Configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Using Bun (bunx - Recommended for speed):

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

Using Node.js (npx):

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

🛠️ MCP Tools Reference

1. calculate_bazi

Calculates Four Pillars, Day Master, Da Yun (Major Luck Cycles labeled with nominal age 虚岁), Branch Interactions (刑冲合会), and Diagnostic Metadata.

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

2. lookup_location

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

🧪 Verification & Benchmark Matrix

@lhk714/bazi-mcp is verified against 100 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