shunshi-bazi-mcp

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

MCP (Model Context Protocol) server — powered by Shunshi.AI / 顺时.

Give Claude Desktop, Cursor, Cline, or any MCP-compatible AI agent the ability to compute full Bazi / 四柱推命 / 사주팔자 charts. Uses the same calculation engine as shunshi.ai's production backend, with true solar time correction enabled by default — the core accuracy advantage over other Bazi MCPs.

🇯🇵 日本の開発者の方へ: これは中国の「八字 (bāzì)」— 日本で言う四柱推命を AI エージェント (Claude / Cursor / Cline など) から使えるようにする MCP サーバーです。生年月日・出生時刻・出生地を伝えるだけで、AI が自動で四柱 / 十神 / 大運 / 五行バランスを計算します。真太陽時（均時差）補正もデフォルトで有効。

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

Why this MCP?

| | cantian-ai/bazi-mcp | shunshi-bazi-mcp | |---|---|---| | Calculation engine | cantian-tymext | shunshi-bazi-core (production engine behind shunshi.ai) | | True solar time | ❌ Clock time only | ✅ Built-in, default on (just pass city or longitude/latitude) | | 子时分日法 | Default sect 2 (23:00 = today) | Default sect 1 (23:00 = tomorrow), matches 问真八字 | | 刑冲合会 | ✅ with 拱/双合/伏吟/半三合 | ✅ classical pair-wise (合/冲/刑/害/破/克) | | 大运 enriched | Partial | ✅ 15 fields per decade incl. 当前 (isCurrent), 藏干十神, 日主关系 | | Parity-tested | — | ✅ vs Shunshi.AI Python backend + cantian on 5 golden cases |

The two MCPs are complementary, not competing. Use whichever gives you the output shape you need. We chose different defaults based on what matches professional Bazi practice in the Chinese-speaking world.

Install

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Restart Claude Desktop. The getBaziChart tool will show up automatically in the 🔨 tools menu.

Note: If npx isn't on Claude Desktop's subprocess PATH (common on macOS with Homebrew node), use the absolute path:

{
  "command": "/opt/homebrew/bin/npx",
  "args": ["-y", "shunshi-bazi-mcp"]
}

Cursor

Edit ~/.cursor/mcp.json (or the equivalent per-workspace file):

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

Cline (VS Code extension)

Open Cline settings → MCP Servers → cline_mcp_settings.json:

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

Continue

Edit ~/.continue/config.json, under experimental.modelContextProtocolServers:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "shunshi-bazi-mcp"]
        }
      }
    ]
  }
}

Generic MCP client (stdio transport)

The server exposes the standard stdio MCP transport. Any client can spawn it as:

npx -y shunshi-bazi-mcp

Global install (optional)

If you don't want to go through npx every time:

npm install -g shunshi-bazi-mcp
# binary: shunshi-bazi-mcp

Then reference the binary directly in your config: "command": "shunshi-bazi-mcp".

Usage

Once installed, just ask your AI agent in natural language. The tool auto-triggers whenever the conversation involves birth date + time + optional location:

中文

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

"1985 年 6 月 15 日下午 2 点整在乌鲁木齐出生的女生，命盘是什么？"

English

"Compute the Bazi chart for a male born 1990-03-24 10:28 in Guangzhou."

"What's the Four Pillars for a person born July 14, 1990 at 00:19 in Shanghai?"

日本語

"1990 年 3 月 24 日 10:28 に東京で生まれた男性の四柱推命を出して。"

"大阪生まれの 1985-06-15 14:00 女性の命盘を計算してください。"

한국어

"1990년 3월 24일 오전 10시 28분 서울 출생 남자의 사주팔자를 계산해줘."

"부산에서 1985년 6월 15일 오후 2시에 태어난 여자의 대운을 알려줘."

The agent will parse your prompt, call getBaziChart with the right parameters, and receive a full structured chart back — including true solar time correction (when a city or coordinates are mentioned) and rich 大运 / 刑冲合会 / 神煞 data.

What does Claude actually do with the output?

When Claude Desktop receives the JSON, it typically:

1. Generates a visual artifact — an HTML/React card rendering the 四柱, 五行 bar chart, 刑冲合会 pills, and 大运 timeline. (You didn't ask for it; Claude generates it because the data is structured enough to visualize.)
2. Writes a natural-language analysis — 日主格局, 五行偏颇, 神煞亮点, 当前大运, 婚恋 etc.
3. Mentions the data source — the top-level 数据来源 field ensures the Shunshi.AI attribution appears at the bottom of the artifact card.

Tool: getBaziChart

Computes a full Bazi (Chinese Four Pillars) chart from birth date, time, and location.

Parameters

| Name | Type | Required | Description | |---|---|---|---| | year | number | ✅ | 公历年份, e.g. 1990 | | month | number | ✅ | 公历月份 1-12 | | day | number | ✅ | 公历日 | | hour | number | ✅ | 小时 0-23 (clock time, uncorrected) | | minute | number | | 分钟 0-59, default 0 | | gender | 0 | 1 | ✅ | 0 = 女, 1 = 男 | | city | string | | 出生城市名 (e.g. "北京", "东京", "首尔"). Triggers true solar time correction. 90+ cities cached across 🇨🇳🇭🇰🇲🇴🇹🇼 Greater China, 🇯🇵 Japan, 🇰🇷 Korea, 🌏 SE Asia, 🇺🇸🇨🇦 North America, 🇦🇺 Oceania, 🇪🇺 Europe. Accepts 繁體中文 / 日本漢字 (東京, 神戸) / 한글 (서울, 부산) aliases. | | longitude | number | | 出生地经度 (° E). Use with latitude to bypass the city cache. | | latitude | number | | 出生地纬度 (° N). | | useTrueSolarTime | boolean | | Default true. Only takes effect if city or longitude+latitude is provided. | | sect | 1 | 2 | | 子时分日法. Default 1 (23:00-23:59 日干支算明天, matches 问真). 2 = 算当天. |

Output

Returns a structured JSON object with:

• 输入 — normalized input (公历, 性别, city, lon/lat)
• 真太阳时 — correction applied (only present if location was given): 钟表时间, 真太阳时, 修正分钟, 时辰, 时辰索引
• 八字 — the full chart:
  • 四柱 — 年月日时 four pillars
  • 日主 / 生肖
  • 柱位详细 — per-pillar: 干支, 天干, 地支, 纳音, 五行, 主星, 副星, 藏干, 藏干详情, 星运, 自坐, 空亡, 神煞
  • 五行分值 — 分值 + 占比 for 金木水火土 + 日主五行
  • 刑冲合会 — { 天干: [], 地支: [] } pair-wise relations (合/冲/刑/害/破/克)
  • 起运 / 起运日期
  • 大运 — 9 decades, each with 起始/结束年龄, 起始/结束年份, 干支, 天干, 地支, 天干五行, 纳音, 主星, 藏干十神, 自坐, 星运, 空亡, 日主关系, 当前 (isCurrent)
  • 命宫 / 身宫 / 胎元 / 胎息
  • 农历 / 公历

Tool: getHuangli

Returns the 黄历 (老黄历 / Chinese almanac) for a given day — built on the same tyme4ts calendar core as the bazi engine, so 黄历 stays consistent with 八字 流日.

Ask in natural language:

"今天的黄历宜忌是什么？" · "帮我看看 2026 年 5 月 31 日适合搬家吗？" · "农历七月初七那天的黄历。" · "What's auspicious today?"

Parameters

| Name | Type | Required | Description | |---|---|---|---| | year | number | | 年份 (公历年, or 农历年 when isLunar). Omit the whole date to get today. | | month | number | | 月份 1-12. | | day | number | | 日 1-31 (农历日 1-30). | | isLunar | boolean | | Default false. true = parse year/month/day as a 农历 (lunar) date. | | isLeapMonth | boolean | | Default false. true marks the input month as a leap month (only with isLunar). |

Output

Returns { 黄历, 数据来源, 说明 } where 黄历 contains:

• 宜 / 忌 — auspicious activities / things to avoid
• 公历 / 星期 / 农历 / 生肖 / 干支 (年/月/日) / 节气 / 星座
• 彭祖百忌 (天干 + 地支) · 神煞 { 吉神: [], 凶煞: [] }
• 十二神 { 建除, 黄黑道 } · 二十八宿 · 九星 · 六曜 · 胎神 · 月相
• 吉神方位 { 喜神, 财神, 福神, 阳贵, 阴贵, 太岁 }
• 节令 { 三伏, 数九, 梅雨, 物候 } (null outside the period)
• 节日 — 公历 + 农历 festivals on the day
• 时辰宜忌 — per-时辰 宜/忌 (13 entries, 早/晚子时 split)

Programmatic use

You usually want the MCP server, but if you're embedding this in a Node.js app directly, use shunshi-bazi-core instead — it's the same calculation engine without the MCP SDK overhead (~500KB saved in your bundle).

// ❌ Don't do this in a frontend / library
import { createServer } from 'shunshi-bazi-mcp';

// ✅ Do this instead
import { getBaziChart } from 'shunshi-bazi-core';

Accuracy

This MCP is a thin wrapper over shunshi-bazi-core, which is parity-tested on every release against:

1. Shunshi.AI's Python backend — 5 golden cases, 5/5 match on 四柱 / 十神 / 空亡 / 纳音 / 藏干
2. cantian-tymext's calculateRelation() — 5/5 match on 刑冲合会 (pair-wise subset)

See shunshi-bazi-core README for details and how to run the tests yourself.

Troubleshooting

The getBaziChart tool doesn't show up in my AI client

1. Did you restart the client? Claude Desktop / Cursor / Cline all spawn MCP servers at startup. Config changes require a full restart.
2. Does npx work from your shell? Try npx -y shunshi-bazi-mcp directly — if it hangs or errors, there's an npx / Node issue.
3. On macOS with Homebrew Node, Claude Desktop's subprocess PATH usually does not include /opt/homebrew/bin. Use the absolute path in your config:

   "command": "/opt/homebrew/bin/npx"
   // or
   "command": "/opt/homebrew/bin/node",
   "args": ["/absolute/path/to/dist/stdio.js"]

4. Check the MCP logs. On Claude Desktop:

   tail -f ~/Library/Logs/Claude/mcp-server-shunshi-bazi.log

   Errors during initialize / tools/list are the most common failure mode.

"City ... not in built-in cache" error

The city you passed isn't in the 90+ city cache. Options:

1. Pass longitude + latitude instead (works for any location on Earth).
2. Try the Simplified Chinese name (东京 instead of tokyo) or a Traditional form (東京).
3. Open an issue and we'll add the city.

The 真太阳时 correction looks wrong for my city (Seoul / Paris / a few others)

This is a known limitation inherited from the Shunshi.AI Python backend's convention:

The engine defaults standardMeridian = round(longitude / 15) × 15°. This works for cities whose local legal timezone's standard meridian is close to their actual longitude (Tokyo 139.65° → JST 135°, perfect), but produces wrong corrections for:

| City | Longitude | Rounds to | Actual legal SM | Problem | |---|---|---|---|---| | 🇰🇷 Seoul (首尔) | 126.98° | 120° | 135° (KST) | Correction off by ~32 min | | 🇫🇷 Paris (巴黎) | 2.35° | 0° | 15° (CET) | Correction off by ~52 min | | 🇨🇳 Urumqi (乌鲁木齐) | 87.62° | 90° | 120° (CST legal) | Matches 问真八字's convention, not Beijing clock time |

Workaround for Seoul / Paris: Convert your clock time to the rounded-meridian timezone first. For Seoul (KST = UTC+9 rounds to 120° = UTC+8), subtract 1 hour before entering. For Paris (CET = UTC+1 rounds to 0° = UTC), subtract 1 hour.

Proper fix: v0.2 will add an explicit standardMeridian parameter so users can override the rounding. Track progress here.

The tool is called but returns an error

Look for the specific error. Common ones:

• gender must be 0 or 1 — You passed "male" or "男" as a string instead of 1. The underlying library expects numeric input; Claude usually converts correctly from natural language, but if you're driving the MCP from code, pass numbers.
• month/day/hour out of range — Same reason. Check your caller.
• City "..." not in built-in cache — See above.

The Bazi output disagrees with 问真八字 / another tool

Before filing a bug, check three things:

1. Did you pass city or longitude/latitude? 问真八字 uses clock time as-is. To match, pass useTrueSolarTime: false.
2. Are you on the 23:00-00:59 boundary? Some tools default to sect=2 (23:00 = today's pillar). Pass sect: 2 to match.
3. Near 立春? The solar year flips at 立春, not Jan 1. But this is handled automatically by tyme4ts under the hood — it's rarely the source of discrepancies.

If after checking all three the output still differs, please open an issue with the exact input and expected output.

FAQ

Is this different from cantian-ai/bazi-mcp?

Yes. See the comparison table at the top of this README. TL;DR:

• We have true solar time correction built in; they don't.
• We default to sect=1 (matches 问真八字); they default to sect 2.
• They compute extra relations (拱/双合/伏吟/半三合); we stick to the pair-wise subset that matches Shunshi.AI's production backend.
• Both are open source under MIT. Pick whichever matches the conventions your users expect.

Can I use this with Cursor / Cline / Continue / other MCP clients?

Yes. Install instructions for each are in the Install section above. The server is transport-agnostic — any client that speaks stdio MCP can use it.

Can I use this in a browser / React app?

No — MCP servers run as subprocesses, so they need a Node.js environment. For browser / React / frontend use cases, install shunshi-bazi-core directly. It's the same calculation engine, ~500KB smaller (no MCP SDK), and works in any bundler.

Does it phone home to Shunshi.AI?

No. The calculation is 100% local. The MCP server doesn't make any network requests. Shunshi.AI attribution only appears in the returned JSON's 数据来源 field (so Claude can show it in the chart visualization) and in this README — there's no telemetry.

How often do you update this?

When we ship meaningful changes. The underlying shunshi-bazi-core library is parity-tested on every release against Shunshi.AI's Python backend — if the backend adds features (e.g. 三合, 动态神煞, 流年 detail), we port them over and bump the minor version.

Can I contribute?

Yes. Open an issue or PR at https://github.com/shunshi-ai/bazi-reader-mcp. Particularly welcome:

• New city entries (with accurate coordinates + source).
• JP / KR / EN translations of field labels (v0.2).
• Additional parity test cases (hand-labeled screenshots from reference tools).

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 built this MCP server to make the same calculation engine that powers shunshi.ai accessible from any AI agent — so developers can build Bazi-aware assistants without rolling their own chart calculator (and getting the 真太阳时 and 子时 edge cases wrong).

License

MIT © 2026 Shunshi.AI

Acknowledgements

• Model Context Protocol by Anthropic
• cantian-ai/bazi-mcp — pioneering open-source Bazi MCP
• tyme4ts by 6tail — lunar/solar calendar primitives