Bazi Reader MCP

What shunshi-ai/bazi-reader-mcp MCP server does

The shunshi-ai/bazi-reader-mcp MCP server provides an MCP interface to a TypeScript calculation engine for Bazi, also known as Four Pillars, 四柱推命, or 사주팔자. It calculates a chart from a person's birth date, birth time, gender, and place information. Results can include the Four Pillars, Ten Gods, major luck periods, Five Elements balance, and additional relationship and deity data supported by the underlying library.

It also provides Huangli, or traditional Chinese almanac, lookups. A request can use a Gregorian or lunar-calendar date, or omit the date to request today's data. Huangli results cover items such as recommended and unsuitable activities, Pengzu taboos, deities, construction-day classifications, lunar mansions, auspicious directions, and time-period guidance.

How it works

The MCP package is a thin server around the separately published shunshi-bazi-core package. MCP clients start the server as a local stdio process and invoke its tools using structured requests. The server exposes two tools:

• getBaziChart calculates a complete Bazi chart and related information.
• getHuangli returns almanac information for a specified day or for today.

For chart requests, true solar time correction is enabled by default when a city or longitude and latitude are provided. The implementation also uses sect=1 by default, which places the 23:00 hour in the following day's pillar according to the project's documented convention. The calculation library is written in TypeScript and can also be used independently in Node.js or browser applications, but that direct library use is separate from the MCP server.

Setup and configuration

Install and run the MCP server with Node.js 20 or newer using:

npx -y shunshi-bazi-mcp

Add that command to an MCP client's server configuration. For Claude Desktop, Cursor, and Cline, the configuration uses npx as the command and -y shunshi-bazi-mcp as its arguments. Restart the client after saving the configuration, then send a natural-language request for a chart or almanac lookup.

The shunshi-ai/bazi-reader-mcp MCP server does not document API keys, tokens, external service credentials, or required environment variables. Its documented quick-start path runs the published npm package locally.

Tools and capabilities

The chart tool includes true solar time correction, major luck periods, and relationship information such as combinations, clashes, punishments, harms, breaks, and controls where applicable. The README states that the calculation engine has been parity-tested against selected Shunshi.AI backend cases and relation results from cantian-tymext.

The almanac tool accepts either solar or lunar dates. Its documented output includes daily recommendations and taboos, auspicious directions, and guidance for the twelve traditional time periods. The project describes terminology and usage for Chinese, English, Japanese, and Korean audiences, including the terms 四柱推命 and 사주팔자.

Limitations and notes

The documented server transport is local stdio; no hosted endpoint is provided. The project does not describe a natural-language interpretation or consultation tool beyond returning calculated chart and almanac data. Chart results depend on the supplied birth details and location, and the project's stated day-pillar behavior follows its sect=1 default. The repository is MIT licensed, while the separate Shunshi.AI product is described independently from this open-source package.