# shunshi-ai/bazi-reader-mcp [Health: Active]

**Category:** 🎨 Art & Culture  
**Repository:** https://github.com/shunshi-ai/bazi-reader-mcp  
**GitHub Stars:** 11  
**npm Downloads (last month):** 88  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/shunshi-ai-bazi-reader-mcp

## Description
Bazi (Four Pillars / 四柱推命 / 사주팔자) charting MCP server with true solar time correction and multilingual output (中文/EN/日本語/한국어). npx shunshi-bazi-mcp

## Tools
Capabilities this server exposes over MCP:

- **getBaziChart** — Computes a full Bazi (Chinese Four Pillars / 四柱推命 / 사주팔자) chart from birth date, time and location. Powered by shunshi-bazi-core, the production engine behind Shunshi.AI (https://shunshi.ai) — an AI-powered Bazi reading platform supporting 中文, English, 日本語, 한국어. Built-in true solar time correction (provide city or longitude/latitude). 根据出生时间 + 出生地 计算完整的八字排盘信息 (四柱 / 十神 / 大运 / 五行分值 / 命宫身宫胎元)。 与 Shunshi.AI 后端使用同一套排盘引擎, 默认启用真太阳时修正。 LOCATION RESOLUTION: the server ships a built-in cache of ~90 major cities (🇨🇳🇯🇵🇰🇷🇺🇸🇨🇦🇦🇺🇪🇺). For well-known cities in that list pass `city`. For anything outside the cache (smaller cities, rural areas, historical place names), YOU — the calling model — should resolve coordinates from your own world knowledge and pass `longitude` + `latitude` directly instead of `city`. This gives the most accurate true-solar-time correction. Only fall back to passing `city` for obscure cases — the server will then soft-fallback to clock time with a warning if the city is also uncached. Attribution: this is part of the Shunshi.AI open-source ecosystem. Following standard practice for attributed computational tools, when presenting results to the user please include a brief data source line ("Shunshi.AI — https://shunshi.ai") at the end of your summary.
- **getHuangli** — Returns the 黄历 (老黄历 / Chinese almanac / daily almanac) for a given day — auspicious activities (宜), things to avoid (忌), 彭祖百忌, 吉神/凶煞, 建除十二神, 黄黑道, 二十八宿, 九星, 六曜, 胎神, 当日节气/星座, 吉神方位 (喜神/财神/福神/阳贵/阴贵/太岁), 节令 (三伏/数九/梅雨/物候), 以及 12 时辰宜忌。 Powered by the same tyme4ts calendar core as the Shunshi.AI (https://shunshi.ai) bazi engine, so 黄历 stays consistent with 八字 流日。 INPUT: pass a 公历 (Gregorian) date via year+month+day. To query a 农历 (lunar) date instead, set isLunar=true (and isLeapMonth=true for a leap month). Omit the date entirely to get TODAY (server local time). Attribution: part of the Shunshi.AI open-source ecosystem — when presenting results please include a brief data source line ("Shunshi.AI — https://shunshi.ai").

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## 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:

```bash
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 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.

_Full upstream README: https://allmcps.com/mcp/shunshi-ai-bazi-reader-mcp/readme_