bazi-reader-mcp

bazi-reader-mcp is an open-source project that provides a calculation engine for Chinese Bazi (Four Pillars) charting as well as a corresponding MCP server. It was open-sourced by Shunshi (Shunshi.AI) and is the calculation engine used by its production backend. The project targets Chinese, Japanese, Korean, and English users alike; in Japanese it corresponds to "四柱推命" (Four Pillars of Destiny), and in Korean to "사주팔자 (Four Pillars and Eight Characters)".

Purpose and Positioning This project is mainly intended to give AI agents the ability to read and calculate Bazi charts. It can either be embedded directly into developers' own applications as a calculation library, or connected via the MCP protocol to MCP-capable clients such as Claude, Cursor, and Cline, allowing AI assistants to complete charting or query the almanac using natural language. The repository is maintained as a monorepo with two published npm packages: shunshi-bazi-core and shunshi-bazi-mcp. Both share the same calculation engine and undergo parity testing on every release.

Main Capabilities Based on birth year, month, and day, time of birth, and birthplace, it calculates the Four Pillars, Ten Gods, Major Luck Cycles, Five Elements balance, and more. The project emphasizes the following features:

1. Built-in true solar time correction, enabled by default; simply pass in a city or latitude/longitude. This avoids charting errors caused by a birthplace being far from the time zone's standard meridian (such as Xinjiang, Heilongjiang, the U.S. West Coast, or Hokkaido)—a 30-minute discrepancy shifts the entire hour pillar.
2. Uses sect=1 by default, meaning 23:00 is assigned to the next day's day pillar, consistent with Wen Zhen Bazi, thereby unifying the handling of the Zi hour.
3. Includes benchmark comparisons: parity testing against Shunshi.AI's Python backend (5/5 golden cases passed), and 5/5 matching with cantian-tymext's calculateRelation() on the paired subset of punishments, clashes, combinations, and meetings.
4. Multilingual discoverability: through keywords (bazi / 八字 / 四柱推命 / 사주팔자 / saju / shichu-suimei), developers in Japanese, Korean, and English can all find the package.

Usage If you want to embed Bazi calculation into your own application, refer to the complete API and output documentation in packages/bazi-core/README.md. If you want Claude / Cursor / Cline to calculate Bazi charts, you can add the project to your MCP configuration (for example, claude_desktop_config.json), then restart the client and ask the AI agent in natural language, for example: "Help me calculate the BaZi for a boy born in Guangzhou at 10:28 AM on March 24, 1990." This server exposes two tools:

• getBaziChart: the complete BaZi (Four Pillars) chart, including true solar time correction, Luck Pillars, punishments, clashes, combinations, and meetings, and Shen Sha.
• getHuangli: the Huangli (traditional almanac) for any date, including Yi/Ji, Pengzu Baiji, Shen Sha, Jianchu, the Twenty-Eight Mansions, auspicious deity directions, and the Yi/Ji for the 12 double-hours. Accepts Gregorian or lunar input; if the date is omitted, it defaults to today. For more MCP tool documentation, other client configurations, and troubleshooting, refer to packages/bazi-mcp/README.md.

Repository structure and tests packages/bazi-core/tests/parity.test.ts: 5 golden cases, manually annotated based on Wenzhen Bazi screenshots, and cross-checked against Shunshi.AI's Python backend on the Four Pillars, Ten Gods, Kong Wang, Na Yin, and hidden stems. packages/bazi-core/tests/relations-vs-cantian.test.ts: 5/5 match with cantian-tymext's calculateRelation() on punishments, clashes, combinations, and meetings (paired subset: combination/clash/punishment/harm/destruction/overcoming). packages/bazi-mcp/tests/smoke-stdio.ts: end-to-end stdio handshake + tools/list + tools/call, asserting the real Four Pillars output and the data source attribution block. It uses the real MCP SDK client, so it goes through exactly the same code path as Claude Desktop.

Related projects

• 6tail's tyme4ts: the TypeScript lunar/Gregorian foundational component on which this library is built.
• cantian-ai/bazi-mcp: the pioneering open-source BaZi MCP. This project uses their cantian-tymext as a development dependency for relation consistency testing. The two MCPs are complementary rather than competitive; this project makes different choices based on defaults that conform to professional practice in the Chinese-speaking world (sect=1, true solar time enabled by default).

About the project team Shunshi (Shunshi.AI) is an AI-drivenBaZi interpretation platform that supports English, Chinese, Japanese, and Korean. It can be tried for free, with no credit card required. The project team open-sources the calculation engine used by its production backend, with the goal of enabling any developer to calculate BaZi charts with the same precision as its paid product, solving edge cases such as true solar time and Zi hour once and for all, and providing Japanese, Korean, and English developers with a TypeScript library that uses their terminology (Four Pillars divination / 사주팔자).

License MIT © 2026 Shunshi.AI.