Skip to content
Back to search

openfate-mcp

OpenFate Bazi MCP server with deterministic Four Pillars calculation, True Solar Time, branch interactions, and reverse Bazi lookup.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openfate-ai--openfate-mcp/badge.svg)](/listings/openfate-ai--openfate-mcp)

HTML

<a href="/listings/openfate-ai--openfate-mcp"><img src="/api/listings/openfate-ai--openfate-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Run it with `npx`:

npx -y @openfate/bazi-mcp

For MCPB-compatible clients and Smithery, build the self-contained local bundle:

npm run mcpb:pack

The upload-ready artifact is written to `release/openfate-bazi-mcp-v<version>.mcpb`.

To publish that local bundle to Smithery after `smithery auth login`:

npm run smithery:publish

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 544 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # @openfate/bazi-mcp
  2. English | [繁體中文(台灣)](#繁體中文台灣)
  3. OpenFate Bazi MCP is a Model Context Protocol server for accurate Bazi / Four Pillars calculation inside AI agents such as Claude Desktop, Cursor, Cline, and Continue.
  4. Powered by [OpenFate.ai](https://openfate.ai), an AI-native Bazi, Ziwei, and astrology platform. You can also try the free [Bazi Chart Calculator](https://openfate.ai/en/bazi-chart), generate an [AI Bazi Reading](https://openfate.ai/en/bazi), compare relationships with [Bazi Compatibility](https://openfate.ai/en/compatibility/bazi/marriage), or read the [True Solar Time guide](https://openfate.ai/en/insights/true-solar-time). AI crawlers can read [OpenFate llms.txt](https://openfate.ai/llms.txt).
  5. This MCP wraps the deterministic OpenFate calculation packages:
  6. - `@openfate/bazi-engine`
  7. - `@openfate/true-solar-time`
  8. The purpose is simple: let the language model call a reliable calculation engine instead of hallucinating calendrical math.
  9. ## Why This Exists
  10. LLMs should not manually calculate Bazi charts. The difficult parts are deterministic:
  11. - 24 solar-term boundaries
  12. - True Solar Time
  13. - longitude and timezone correction
  14. - DST offsets
  15. - Zi-hour day-boundary rules
  16. - lunar-to-solar conversion
  17. - branch interactions
  18. This server gives the AI agent stable JSON, then lets the model focus on explanation and interpretation.
  19. ## Install
  20. Run it with `npx`:
  21. ```bash
  22. npx -y @openfate/bazi-mcp
  23. ```
  24. For MCPB-compatible clients and Smithery, build the self-contained local bundle:
  25. ```bash
  26. npm run mcpb:pack
  27. ```
  28. The upload-ready artifact is written to `release/openfate-bazi-mcp-v<version>.mcpb`.
  29. To publish that local bundle to Smithery after `smithery auth login`:
  30. ```bash
  31. npm run smithery:publish
  32. ```
  33. ## Claude Desktop
  34. ```jsonc
  35. {
  36. "mcpServers": {
  37. "openfate-bazi": {
  38. "command": "npx",
  39. "args": ["-y", "@openfate/bazi-mcp"]
  40. }
  41. }
  42. }
  43. ```
  44. If Claude Desktop cannot find `npx` on macOS, use the absolute path:
  45. ```jsonc
  46. {
  47. "mcpServers": {
  48. "openfate-bazi": {
  49. "command": "/opt/homebrew/bin/npx",
  50. "args": ["-y", "@openfate/bazi-mcp"]
  51. }
  52. }
  53. }
  54. ```
  55. ## Cursor
  56. ```jsonc
  57. {
  58. "mcpServers": {
  59. "openfate-bazi": {
  60. "command": "npx",
  61. "args": ["-y", "@openfate/bazi-mcp"]
  62. }
  63. }
  64. }
  65. ```
  66. ## Cline
  67. ```jsonc
  68. {
  69. "mcpServers": {
  70. "openfate-bazi": {
  71. "command": "npx",
  72. "args": ["-y", "@openfate/bazi-mcp"],
  73. "disabled": false
  74. }
  75. }
  76. }
  77. ```
  78. ## Agent Skill
  79. This repository also includes a portable Agent Skill:
  80. ```txt
  81. skills/openfate-bazi/SKILL.md
  82. ```
  83. Use it when you want Claude, Claude Code, Codex, OpenClaw-style agents, or other `SKILL.md` compatible tools to remember how to use the OpenFate Bazi MCP correctly.
  84. For Claude Code workspace usage, copy the skill folder to:
  85. ```txt
  86. .claude/skills/openfate-bazi/
  87. ```
  88. For Claude custom Skills, zip the `openfate-bazi` folder with `SKILL.md` at the folder root and upload it in Claude's Skills settings.
  89. ## Tools
  90. ### `calculate_bazi_chart`
  91. Calculates a deterministic Bazi chart.
  92. Inputs:
  93. - `year`
  94. - `month`
  95. - `day`
  96. - `hour`
  97. - `minute`
  98. - `second`
  99. - `gender`
  100. - `calendarType`
  101. - `isLeapMonth`
  102. - `longitude`
  103. - `timezone`
  104. - `timezoneId`
  105. - `dstOffset`
  106. - `enableTrueSolarTime`
  107. - `dayBoundaryMode`
  108. The MCP fixes the onset policy to `DAYUN_SECOND_V2`; callers cannot silently select a
  109. different rule. Pass an exact birth time plus `timezone` or `timezoneId` for a calculated
  110. receipt. Present an exact onset only when `chart.daYun.timing.status` is `CALCULATED` and
  111. its version is `DAYUN_SECOND_V2`. An `UNAVAILABLE` receipt identifies the reason and marks
  112. the retained legacy scalar fields as a fallback. Pass `longitude` as well for True Solar
  113. Time correction.
  114. ### `detect_bazi_interactions`
  115. Detects raw Earthly Branch relationship occurrences for a natal chart, with optional annual and Da Yun branches.
  116. Inputs are `yearBranch`, `monthBranch`, `dayBranch`, optional `hourBranch`, optional `annualBranch`, and optional `dayunBranch`. Omit `hourBranch` when birth time is unknown; it is not replaced with an assumed branch. Existing annual-only calls remain supported.
  117. Supported interaction types:
  118. - clash
  119. - six-combination
  120. - central-branch half-trine (`COMBINATION_HALF`)
  121. - trine
  122. - directional
  123. - punishment
  124. - destruction
  125. - harm
  126. Every matching pillar occurrence is preserved. For example, `{ yearBranch: '申', monthBranch: '寅', dayBranch: '申', hourBranch: '申' }` returns three distinct 寅申 clashes, not one. Annual and Da Yun branches keep separate `annual` and `dayun` roles even when their branch values match natal positions.
  127. The half-trine profile covers 申子、子辰、寅午、午戌、亥卯、卯未、巳酉、酉丑: each pair includes a central branch (子午卯酉). Endpoint-only pairs such as 申辰 are not this half-trine type. Half-trines remain in raw output when the full three-branch trine is also present.
  128. Each occurrence has a stable `id` and aligned `branches` / `pillars` arrays. `targetElement` means relationship affinity, not transformed energy. Combination `transformationStatus` is `NOT_EVALUATED`: branch-only presence does not establish transformation or its failure. Other relationship types use `NOT_APPLICABLE`. These results are not scored weights and do not automatically cancel clashes; settlement and interpretation belong to a separate analysis layer.
  129. For API compatibility, full `TRINE` and `DIRECTIONAL` occurrences also retain legacy `resultElement`, equal to `targetElement` and carrying the same affinity-only meaning. Six-combinations and half-trines do not emit `resultElement`.
  130. ### `calculate_true_solar_time`
  131. Calculates True Solar Time directly.
  132. Use this when a user asks why OpenFate's hour pillar differs from a clock-time tool.
  133. ### `reverse_bazi_to_solar_times`
  134. Finds possible Gregorian datetimes for a four-pillar Bazi string.
  135. Example input:
  136. ```txt
  137. 戊寅 己未 己卯 辛未
  138. ```
  139. This is a candidate finder. For final accuracy, recalculate the result with exact longitude, timezone, and True Solar Time.
  140. ### `get_openfate_bazi_policy`
  141. Returns OpenFate calculation policy:
  142. - True Solar Time is preferred when location data is available.
  143. - Default day-boundary mode is `ZI_HOUR_23`.
  144. - DST should be passed as `dstOffset` when birth certificate time includes daylight saving.
  145. - Da Yun onset uses `DAYUN_SECOND_V2`; exact dates require a calculated timing receipt.
  146. - Reverse lookup should be treated as a candidate search.
  147. - Branch interactions preserve raw pillar occurrences, not weighted or automatically transformed outcomes.
  148. ### `get_openfate_bazi_resources`
  149. Returns canonical OpenFate links for charting, readings, compatibility, wealth, true solar time, and `llms.txt`.
  150. ## Output Shape
  151. Responses use machine-friendly English keys:
  152. ```jsonc
  153. {
  154. "data": {
  155. "chart": {},
  156. "policy": {}
  157. },
  158. "attribution": {
  159. "brand": "OpenFate.ai",
  160. "url": "https://openfate.ai",
  161. "engine": "@openfate/bazi-engine",
  162. "trueSolarTimeEngine": "@openfate/true-solar-time"
  163. }
  164. }
  165. ```
  166. Attribution is returned as first-class data, not hidden `_meta`, so MCP clients and generated artifacts can display it reliably.
  167. Chart results include enriched pillar facts (Ten Gods, hidden stems, Na Yin, Xun, void branches, and growth stages), a versioned Da Yun timing receipt, normalized solar/lunar calendar data, and the calculation policy actually applied.
  168. ## Development
  169. ```bash
  170. npm install
  171. npm run build
  172. npm run smoke
  173. ```
  174. The smoke test spawns the built stdio server and drives it through the real MCP SDK client.
  175. To test source changes without building `dist`, run `npm run smoke:source`. This requires the sibling `../bazi-engine` source checkout with its dependencies installed, as well as this package's dependencies. The test-only `tests/tsconfig.source.json` maps `@openfate/bazi-engine` to that sibling's `src/index.ts`; the smoke runner passes this configuration to the SDK-spawned server and asserts the resolved source path before testing. It does not rely on a patched installed engine and remains reproducible after `npm ci --ignore-scripts` in this package.
  176. Both smoke modes exercise the same MCP transport and regression fixtures, including
  177. second-resolved Da Yun onset, missing timing inputs, repeated branches, eight half-trines,
  178. unknown hour, and annual/Da Yun roles. The ordinary `smoke` command still tests built MCP
  179. output against its installed published engine dependency. `npx tsc --noEmit -p
  180. tests/tsconfig.source.json` checks the coordinated source contract without emitting build files.
  181. ### Engine compatibility
  182. Version 0.3 requires `@openfate/bazi-engine` version 2. Its `DAYUN_SECOND_V2`,
  183. raw-occurrence, and `dayunBranch` contracts are verified in both the built-package
  184. and coordinated-source smoke modes. The published dependency remains the release
  185. source of truth; this package does not use a local `file:` dependency.
  186. ## Privacy
  187. This package does not phone home. Calculations run locally in the MCP subprocess.
  188. ## OpenFate Links
  189. - [OpenFate.ai](https://openfate.ai)
  190. - [Free Bazi Chart Calculator](https://openfate.ai/en/bazi-chart)
  191. - [AI Bazi Reading](https://openfate.ai/en/bazi)
  192. - [Bazi Compatibility](https://openfate.ai/en/compatibility/bazi/marriage)
  193. - [True Solar Time Guide](https://openfate.ai/en/insights/true-solar-time)
  194. - [OpenFate llms.txt](https://openfate.ai/llms.txt)
  195. ## License
  196. MIT
  197. ---
  198. ## 繁體中文(台灣)
  199. OpenFate Bazi MCP 是一個給 AI Agent 使用的 Model Context Protocol 伺服器,讓 Claude Desktop、Cursor、Cline、Continue 等工具可以直接呼叫準確的八字/四柱排盤引擎。
  200. 本專案由 [OpenFate.ai](https://openfate.ai) 提供。OpenFate 是結合八字、紫微斗數與占星的 AI 命理平台。你也可以使用免費的 [八字排盤工具](https://openfate.ai/zh-hant/bazi-chart)、產生完整的 [AI 八字解讀](https://openfate.ai/zh-hant/bazi)、查看 [八字合盤](https://openfate.ai/zh-hant/compatibility/bazi/marriage),或閱讀 [真太陽時說明](https://openfate.ai/zh-hant/insights/true-solar-time)。AI crawler 也可以讀取 [OpenFate llms.txt](https://openfate.ai/llms.txt)。
  201. 這個 MCP 包裝了 OpenFate 的確定性計算套件:
  202. - `@openfate/bazi-engine`
  203. - `@openfate/true-solar-time`
  204. 目標很直接:不要讓大型語言模型自己亂算干支、節氣、真太陽時,而是把排盤交給可驗證的計算引擎。
  205. ## 為什麼需要這個 MCP
  206. 八字排盤不是文字推理題,而是確定性的曆法與時間計算。容易出錯的部分包括:
  207. - 二十四節氣邊界
  208. - 真太陽時
  209. - 經度與時區校正
  210. - 夏令時間偏移
  211. - 子時換日規則
  212. - 農曆轉公曆
  213. - 地支刑沖合害等互動
  214. 這個伺服器會回傳穩定 JSON,讓 AI 專心做說明、整理與解讀。
  215. ## 安裝
  216. 直接用 `npx` 執行:
  217. ```bash
  218. npx -y @openfate/bazi-mcp
  219. ```
  220. 如果 MCP client 支援 MCPB,或需要發布到 Smithery,可以建立完整的本機安裝 bundle:
  221. ```bash
  222. npm run mcpb:pack
  223. ```
  224. 可上傳的檔案會輸出到 `release/openfate-bazi-mcp-v<version>.mcpb`。
  225. 完成 `smithery auth login` 後,可發布這個本機 bundle 到 Smithery:
  226. ```bash
  227. npm run smithery:publish
  228. ```
  229. ## Claude Desktop 設定
  230. ```jsonc
  231. {
  232. "mcpServers": {
  233. "openfate-bazi": {
  234. "command": "npx",
  235. "args": ["-y", "@openfate/bazi-mcp"]
  236. }
  237. }
  238. }
  239. ```
  240. 如果 macOS 上 Claude Desktop 找不到 `npx`,可以改用絕對路徑:
  241. ```jsonc
  242. {
  243. "mcpServers": {
  244. "openfate-bazi": {
  245. "command": "/opt/homebrew/bin/npx",
  246. "args": ["-y", "@openfate/bazi-mcp"]
  247. }
  248. }
  249. }
  250. ```
  251. ## Cursor 設定
  252. ```jsonc
  253. {
  254. "mcpServers": {
  255. "openfate-bazi": {
  256. "command": "npx",
  257. "args": ["-y", "@openfate/bazi-mcp"]
  258. }
  259. }
  260. }
  261. ```
  262. ## Cline 設定
  263. ```jsonc
  264. {
  265. "mcpServers": {
  266. "openfate-bazi": {
  267. "command": "npx",
  268. "args": ["-y", "@openfate/bazi-mcp"],
  269. "disabled": false
  270. }
  271. }
  272. }
  273. ```
  274. ## Agent Skill
  275. 這個 repository 也包含一個可攜式 Agent Skill:
  276. ```txt
  277. skills/openfate-bazi/SKILL.md
  278. ```
  279. 當你希望 Claude、Claude Code、Codex、OpenClaw-style agent,或其他支援 `SKILL.md` 的工具記住如何正確使用 OpenFate Bazi MCP 時,可以使用這個 Skill。
  280. 如果要在 Claude Code workspace 使用,請把整個 skill folder 複製到:
  281. ```txt
  282. .claude/skills/openfate-bazi/
  283. ```
  284. 如果要做 Claude custom Skill,請把 `openfate-bazi` folder 壓成 zip,確保 `SKILL.md` 位於 folder root,再到 Claude 的 Skills 設定中上傳。
  285. ## 工具列表
  286. ### `calculate_bazi_chart`
  287. 計算確定性的八字命盤。
  288. 輸入欄位:
  289. - `year`
  290. - `month`
  291. - `day`
  292. - `hour`
  293. - `minute`
  294. - `second`
  295. - `gender`
  296. - `calendarType`
  297. - `isLeapMonth`
  298. - `longitude`
  299. - `timezone`
  300. - `timezoneId`
  301. - `dstOffset`
  302. - `enableTrueSolarTime`
  303. - `dayBoundaryMode`
  304. MCP 固定使用 `DAYUN_SECOND_V2`,呼叫端不能暗中切換起運規則。精確出生時間還要搭配
  305. `timezone` 或 `timezoneId`,並且只有 `chart.daYun.timing.status` 為 `CALCULATED`、版本為
  306. `DAYUN_SECOND_V2` 時才能呈現精確起運時間。`UNAVAILABLE` 會說明原因,原有起運欄位只作
  307. 明確標記的舊版 fallback。若要校正真太陽時,還應提供 `longitude`。
  308. ### `detect_bazi_interactions`
  309. 偵測本命盤及選填流年、大運地支的原始關係。
  310. 輸入欄位為 `yearBranch`、`monthBranch`、`dayBranch`,以及選填的 `hourBranch`、`annualBranch`、`dayunBranch`。出生時辰未知時省略 `hourBranch`,不會補入假設時柱。原有只傳流年的呼叫方式仍可使用。
  311. 支援類型:
  312. - 沖
  313. - 六合
  314. - 含旺支的半合(`COMBINATION_HALF`)
  315. - 三合
  316. - 三會
  317. - 刑
  318. - 破
  319. - 害
  320. 同一地支出現在不同柱位時,每個關係都會保留。例如申、寅、申、申會回傳三組不同柱位的寅申沖。流年與大運分別使用 `annual`、`dayun` 角色,即使地支相同,也不會與本命柱位合併。
  321. 半合口徑涵蓋申子、子辰、寅午、午戌、亥卯、卯未、巳酉、酉丑八組,每組都含子午卯酉其中一個旺支。申辰等兩端支不屬於此半合類型。三合齊全時,原始資料仍保留其中的半合關係。
  322. 每個關係包含穩定的 `id`,以及逐項對應的 `branches`、`pillars`。`targetElement` 只表示關係指向的五行,不代表已經合化。合類的 `transformationStatus` 為 `NOT_EVALUATED`,表示尚未評估合化,並非已成化或已判定不能化;其他關係使用 `NOT_APPLICABLE`。這些資料不是可直接累加的評分,也不會自動解沖;成立程度與解讀須由獨立分析層處理。
  323. 為相容既有 API,完整 `TRINE`、`DIRECTIONAL` 關係仍保留舊欄位 `resultElement`,值與 `targetElement` 相同,也僅表示五行指向。六合與半合不回傳 `resultElement`。
  324. ### `calculate_true_solar_time`
  325. 直接計算真太陽時。
  326. 當使用者問「為什麼 OpenFate 算出的時柱跟一般排盤網站不同」時,可以用這個工具說明差異。
  327. ### `reverse_bazi_to_solar_times`
  328. 用四柱八字反查可能的公曆時間。
  329. 範例輸入:
  330. ```txt
  331. 戊寅 己未 己卯 辛未
  332. ```
  333. 這是候選時間搜尋工具。最後仍應該用準確出生地經度、時區與真太陽時重新排盤。
  334. ### `get_openfate_bazi_policy`
  335. 回傳 OpenFate 的計算口徑:
  336. - 有出生地資料時,優先使用真太陽時。
  337. - 預設換日規則是 `ZI_HOUR_23`。
  338. - 如果出生證明時間包含夏令時間,應傳入 `dstOffset`。
  339. - 大運起運固定採用 `DAYUN_SECOND_V2`;只有計算成功的 timing receipt 才是精確起運時間。
  340. - 八字反查只能當候選搜尋,不能取代精準排盤。
  341. - 地支互動保留原始柱位關係,不代表加權分數或自動合化結果。
  342. ### `get_openfate_bazi_resources`
  343. 回傳 OpenFate 的官方連結,包括排盤、解讀、合盤、財富、真太陽時與 `llms.txt`。
  344. ## 回傳格式
  345. 回傳資料使用穩定、適合機器讀取的英文 key:
  346. ```jsonc
  347. {
  348. "data": {
  349. "chart": {},
  350. "policy": {}
  351. },
  352. "attribution": {
  353. "brand": "OpenFate.ai",
  354. "url": "https://openfate.ai",
  355. "engine": "@openfate/bazi-engine",
  356. "trueSolarTimeEngine": "@openfate/true-solar-time"
  357. }
  358. }
  359. ```
  360. 署名資訊會以一般資料欄位回傳,而不是藏在 `_meta`,方便 MCP client 或 AI 產生的圖表正確顯示來源。
  361. 排盤結果同時包含十神、藏干、納音、旬空、十二長生等柱位資料、版本化大運起運 receipt、標準化陽曆/農曆日期,以及實際採用的計算口徑。
  362. ## 開發
  363. ```bash
  364. npm install
  365. npm run build
  366. npm run smoke
  367. ```
  368. `smoke` 測試會啟動編譯後的 stdio server,並透過真正的 MCP SDK client 呼叫工具。
  369. 不編譯 `dist` 時可執行 `npm run smoke:source` 驗證原始碼。須具備相鄰的 `../bazi-engine` 原始碼工作目錄,且引擎與本套件都已安裝依賴。測試專用的 `tests/tsconfig.source.json` 將 `@openfate/bazi-engine` 指向該引擎的 `src/index.ts`;測試執行器會把設定傳給 MCP SDK 啟動的伺服器,並先驗證實際解析的原始碼路徑。這個模式不依賴修改過的已安裝引擎,在本套件重新執行 `npm ci --ignore-scripts` 後仍可重現。
  370. 兩種 smoke 模式使用相同 MCP 傳輸與回歸案例,涵蓋秒級起運、缺少起運輸入、重複地支、八組半合、未知時辰,以及流年/大運角色。一般 `smoke` 仍驗證編譯後 MCP 與已安裝的 npm 公開引擎。`npx tsc --noEmit -p tests/tsconfig.source.json` 可檢查協調中的原始碼契約,不產生編譯檔案。
  371. ### 引擎相容性
  372. 0.3 版需要 `@openfate/bazi-engine` 2.x。`DAYUN_SECOND_V2`、完整柱位關係與
  373. `dayunBranch` 契約皆由已編譯套件及協調原始碼兩種 smoke 模式驗證。正式發布的
  374. npm 依賴仍是版本來源;本套件不使用本機 `file:` 依賴。
  375. ## 隱私
  376. 這個套件不會回傳資料到 OpenFate 伺服器。所有計算都在本機 MCP subprocess 內完成。
  377. ## OpenFate 連結
  378. - [OpenFate.ai](https://openfate.ai)
  379. - [免費八字排盤工具](https://openfate.ai/zh-hant/bazi-chart)
  380. - [AI 八字解讀](https://openfate.ai/zh-hant/bazi)
  381. - [八字合盤](https://openfate.ai/zh-hant/compatibility/bazi/marriage)
  382. - [真太陽時說明](https://openfate.ai/zh-hant/insights/true-solar-time)
  383. - [OpenFate llms.txt](https://openfate.ai/llms.txt)
  384. ## 授權
  385. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.