bazi-reader-mcp

🇨🇳 中国八字 (Four Pillars of Destiny) ・ 🇯🇵 四柱推命 (しちゅうすいめい) ・ 🇰🇷 사주팔자 (四柱八字)

The calculation engine (and MCP server) behind Shunshi.AI / 顺时, open-sourced.

🇯🇵 日本の開発者の方へ: これは中国の「八字 (bāzì)」— 日本で言う 四柱推命 の計算エンジン + MCP サーバーです。生年月日・出生時刻・出生地から四柱 / 十神 / 大運 / 五行バランスを計算できます。真太陽時（均時差）補正にも対応しており、AI エージェント (Claude / Cursor / Cline など) から直接呼び出せます。

🇰🇷 한국 개발자분들께: 중국의 "八字 (bāzì)" — 한국에서는 사주팔자라고 부르는 명리학의 계산 엔진 + MCP 서버입니다. 생년월일·출생시각·출생지로부터 사주 / 십성 / 대운 / 오행 균형을 계산합니다. 진태양시 보정도 지원하며, AI 에이전트 (Claude / Cursor / Cline 등) 에서 바로 사용할 수 있습니다.

---

This repository is a monorepo with two published npm packages:

Package	What it is	Install
shunshi-bazi-core	Pure TypeScript calculation library. Zero framework deps. Use it from any Node.js / browser app.	npm install shunshi-bazi-core
shunshi-bazi-mcp	Thin Model Context Protocol server wrapping the core library. Drop-in tool for Claude Desktop / Cursor / Cline / any MCP client.	npx -y shunshi-bazi-mcp

Both packages share the same calculation engine that powers Shunshi.AI's production backend. Both are parity-tested on every release.

---

Why this exists

Most existing open-source Bazi libraries (in any language) have at least one of these problems:

1. No true solar time correction. Clock time gets used as-is, which gives wrong charts for births far from the timezone's standard meridian (新疆 / 黑龙江 / the U.S. West Coast / 北海道). A 30-minute error shifts the whole hour pillar.
2. Inconsistent 子时 handling. Some libraries put 23:00-23:59 in "yesterday's" day pillar, others in "tomorrow's". If you don't pick, your charts disagree with professional reference tools.
3. No parity baseline. You compute a chart locally, compare against a paid service, get different numbers, and have no way to tell who's right.
4. Raw data only, no multilingual context. Output is Chinese-centric, hard to wire into JP/KR/EN AI assistants.

shunshi-bazi-core + shunshi-bazi-mcp fix all four:

• ✅ True solar time built-in, default on (just pass city or longitude/latitude).
• ✅ Default sect=1 (23:00 = tomorrow's day pillar), matching 问真八字.
• ✅ Parity-tested against Shunshi.AI's Python backend (5/5 golden cases) and cantian-tymext's calculateRelation() (5/5 on 刑冲合会 pair-wise subset).
• ✅ Multilingual discoverability via keywords (bazi / 八字 / 四柱推命 / 사주팔자 / saju / shichu-suimei) so JP/KR/EN developers can find the package.

---

Quick start

If you're embedding Bazi calc in your own app

npm install shunshi-bazi-core

import { getBaziChart } from 'shunshi-bazi-core';

const chart = getBaziChart({
  year: 1990, month: 3, day: 24, hour: 10, minute: 28,
  gender: 1,           // 0 = 女, 1 = 男
  city: '广州',         // triggers true solar time correction
});

console.log(chart.八字.四柱);          // "庚午 己卯 戊子 丁巳"
console.log(chart.真太阳时?.修正分钟); // -33.85 (minutes of correction applied)

→ Full API and output reference: packages/bazi-core/README.md

If you want Claude / Cursor / Cline to compute Bazi charts

Add this to your MCP config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "shunshi-bazi": {
      "command": "npx",
      "args": ["-y", "shunshi-bazi-mcp"]
    }
  }
}

Then restart the client and ask your AI agent in natural language:

"帮我算一下 1990 年 3 月 24 日 上午 10 点 28 分出生在广州的男生的八字。"

The server exposes two tools:

• getBaziChart — full Bazi (Four Pillars) chart with true-solar-time correction, 大运, 刑冲合会, 神煞.
• getHuangli — 黄历 (老黄历 / Chinese almanac) for any day: 宜/忌, 彭祖百忌, 神煞, 建除, 二十八宿, 吉神方位, 12 时辰宜忌. Accepts 公历 or 农历 input; omit the date for today.

"今天的黄历宜忌是什么？"

→ Full MCP tool docs, alternate client configs, troubleshooting: packages/bazi-mcp/README.md

---

Repository layout

bazi-reader-mcp/
├── package.json                 # npm workspace root (private)
├── tsconfig.base.json           # shared TypeScript config
├── LICENSE                      # MIT
├── README.md                    # you are here
└── packages/
    ├── bazi-core/               # → publishes as "shunshi-bazi-core"
    │   ├── src/
    │   │   ├── index.ts
    │   │   └── lib/{bazi,relations,shensha,solarTime,cityCache}.ts
    │   ├── tests/{parity,relations-vs-cantian,smoke}.ts
    │   ├── package.json
    │   └── README.md
    └── bazi-mcp/                # → publishes as "shunshi-bazi-mcp"
        ├── src/{mcp,stdio}.ts
        ├── tests/smoke-stdio.ts
        ├── package.json
        └── README.md

---

Development

# install deps for both packages
npm install

# build both packages
npm run build

# run bazi-core tests (parity + relations-vs-cantian)
npm test

# run the MCP server locally via tsx (no build required)
npm run dev:mcp

# stdio smoke test for the MCP (spawns the built dist/stdio.js)
cd packages/bazi-mcp && npm run smoke

Test coverage

• packages/bazi-core/tests/parity.test.ts — 5 golden cases hand-labeled from screenshots of 问真八字, cross-checked against Shunshi.AI's Python backend on 四柱 / 十神 / 空亡 / 纳音 / 藏干.
• packages/bazi-core/tests/relations-vs-cantian.test.ts — 5/5 match vs cantian-tymext's calculateRelation() on 刑冲合会 (pair-wise subset: 合 / 冲 / 刑 / 害 / 破 / 克).
• packages/bazi-mcp/tests/smoke-stdio.ts — End-to-end stdio handshake + tools/list + tools/call, asserts the real 四柱 output and the 数据来源 attribution block. Uses the real MCP SDK client so it exercises the exact same code path as Claude Desktop.

---

Related projects

• tyme4ts by 6tail — the TypeScript lunar/solar calendar primitives this library builds on.
• cantian-ai/bazi-mcp — pioneering open-source Bazi MCP. We use their cantian-tymext as a dev dependency for relations parity testing. The two MCPs are complementary, not competing — we made different defaults (sect=1, true solar time on by default) based on what matches professional practice in the Chinese-speaking world.

---

About Shunshi.AI

🌐 Website: https://shunshi.ai 🐦 X / Twitter: @shunshiai2026 🚀 Product Hunt: Shunshi.AI

Shunshi.AI (顺时) is an AI-powered Bazi reading platform supporting English, 中文, 日本語, and 한국어. Free to try, no credit card required.

We open-sourced the calculation engine behind our production backend so:

• Any developer can compute Bazi charts with the same accuracy as our paid product.
• The 真太阳时 / 子时 edge cases get solved once and for all, instead of each project getting them wrong in a slightly different way.
• JP/KR/EN developers finally have a TypeScript library that speaks their terminology (四柱推命 / 사주팔자).

---

License

MIT © 2026 Shunshi.AI