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.
Badge for your README
Markdown
[](/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
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)
- # @openfate/bazi-mcp
- English | [繁體中文(台灣)](#繁體中文台灣)
- 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.
- 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).
- This MCP wraps the deterministic OpenFate calculation packages:
- - `@openfate/bazi-engine`
- - `@openfate/true-solar-time`
- The purpose is simple: let the language model call a reliable calculation engine instead of hallucinating calendrical math.
- ## Why This Exists
- LLMs should not manually calculate Bazi charts. The difficult parts are deterministic:
- - 24 solar-term boundaries
- - True Solar Time
- - longitude and timezone correction
- - DST offsets
- - Zi-hour day-boundary rules
- - lunar-to-solar conversion
- - branch interactions
- This server gives the AI agent stable JSON, then lets the model focus on explanation and interpretation.
- ## Install
- Run it with `npx`:
- ```bash
- npx -y @openfate/bazi-mcp
- ```
- For MCPB-compatible clients and Smithery, build the self-contained local bundle:
- ```bash
- 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`:
- ```bash
- npm run smithery:publish
- ```
- ## Claude Desktop
- ```jsonc
- {
- "mcpServers": {
- "openfate-bazi": {
- "command": "npx",
- "args": ["-y", "@openfate/bazi-mcp"]
- }
- }
- }
- ```
- If Claude Desktop cannot find `npx` on macOS, use the absolute path:
- ```jsonc
- {
- "mcpServers": {
- "openfate-bazi": {
- "command": "/opt/homebrew/bin/npx",
- "args": ["-y", "@openfate/bazi-mcp"]
- }
- }
- }
- ```
- ## Cursor
- ```jsonc
- {
- "mcpServers": {
- "openfate-bazi": {
- "command": "npx",
- "args": ["-y", "@openfate/bazi-mcp"]
- }
- }
- }
- ```
- ## Cline
- ```jsonc
- {
- "mcpServers": {
- "openfate-bazi": {
- "command": "npx",
- "args": ["-y", "@openfate/bazi-mcp"],
- "disabled": false
- }
- }
- }
- ```
- ## Agent Skill
- This repository also includes a portable Agent Skill:
- ```txt
- skills/openfate-bazi/SKILL.md
- ```
- 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.
- For Claude Code workspace usage, copy the skill folder to:
- ```txt
- .claude/skills/openfate-bazi/
- ```
- For Claude custom Skills, zip the `openfate-bazi` folder with `SKILL.md` at the folder root and upload it in Claude's Skills settings.
- ## Tools
- ### `calculate_bazi_chart`
- Calculates a deterministic Bazi chart.
- Inputs:
- - `year`
- - `month`
- - `day`
- - `hour`
- - `minute`
- - `second`
- - `gender`
- - `calendarType`
- - `isLeapMonth`
- - `longitude`
- - `timezone`
- - `timezoneId`
- - `dstOffset`
- - `enableTrueSolarTime`
- - `dayBoundaryMode`
- The MCP fixes the onset policy to `DAYUN_SECOND_V2`; callers cannot silently select a
- different rule. Pass an exact birth time plus `timezone` or `timezoneId` for a calculated
- receipt. Present an exact onset only when `chart.daYun.timing.status` is `CALCULATED` and
- its version is `DAYUN_SECOND_V2`. An `UNAVAILABLE` receipt identifies the reason and marks
- the retained legacy scalar fields as a fallback. Pass `longitude` as well for True Solar
- Time correction.
- ### `detect_bazi_interactions`
- Detects raw Earthly Branch relationship occurrences for a natal chart, with optional annual and Da Yun branches.
- 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.
- Supported interaction types:
- - clash
- - six-combination
- - central-branch half-trine (`COMBINATION_HALF`)
- - trine
- - directional
- - punishment
- - destruction
- - harm
- 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.
- 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.
- 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.
- 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`.
- ### `calculate_true_solar_time`
- Calculates True Solar Time directly.
- Use this when a user asks why OpenFate's hour pillar differs from a clock-time tool.
- ### `reverse_bazi_to_solar_times`
- Finds possible Gregorian datetimes for a four-pillar Bazi string.
- Example input:
- ```txt
- 戊寅 己未 己卯 辛未
- ```
- This is a candidate finder. For final accuracy, recalculate the result with exact longitude, timezone, and True Solar Time.
- ### `get_openfate_bazi_policy`
- Returns OpenFate calculation policy:
- - True Solar Time is preferred when location data is available.
- - Default day-boundary mode is `ZI_HOUR_23`.
- - DST should be passed as `dstOffset` when birth certificate time includes daylight saving.
- - Da Yun onset uses `DAYUN_SECOND_V2`; exact dates require a calculated timing receipt.
- - Reverse lookup should be treated as a candidate search.
- - Branch interactions preserve raw pillar occurrences, not weighted or automatically transformed outcomes.
- ### `get_openfate_bazi_resources`
- Returns canonical OpenFate links for charting, readings, compatibility, wealth, true solar time, and `llms.txt`.
- ## Output Shape
- Responses use machine-friendly English keys:
- ```jsonc
- {
- "data": {
- "chart": {},
- "policy": {}
- },
- "attribution": {
- "brand": "OpenFate.ai",
- "url": "https://openfate.ai",
- "engine": "@openfate/bazi-engine",
- "trueSolarTimeEngine": "@openfate/true-solar-time"
- }
- }
- ```
- Attribution is returned as first-class data, not hidden `_meta`, so MCP clients and generated artifacts can display it reliably.
- 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.
- ## Development
- ```bash
- npm install
- npm run build
- npm run smoke
- ```
- The smoke test spawns the built stdio server and drives it through the real MCP SDK client.
- 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.
- Both smoke modes exercise the same MCP transport and regression fixtures, including
- second-resolved Da Yun onset, missing timing inputs, repeated branches, eight half-trines,
- unknown hour, and annual/Da Yun roles. The ordinary `smoke` command still tests built MCP
- output against its installed published engine dependency. `npx tsc --noEmit -p
- tests/tsconfig.source.json` checks the coordinated source contract without emitting build files.
- ### Engine compatibility
- Version 0.3 requires `@openfate/bazi-engine` version 2. Its `DAYUN_SECOND_V2`,
- raw-occurrence, and `dayunBranch` contracts are verified in both the built-package
- and coordinated-source smoke modes. The published dependency remains the release
- source of truth; this package does not use a local `file:` dependency.
- ## Privacy
- This package does not phone home. Calculations run locally in the MCP subprocess.
- ## OpenFate Links
- - [OpenFate.ai](https://openfate.ai)
- - [Free Bazi Chart Calculator](https://openfate.ai/en/bazi-chart)
- - [AI Bazi Reading](https://openfate.ai/en/bazi)
- - [Bazi Compatibility](https://openfate.ai/en/compatibility/bazi/marriage)
- - [True Solar Time Guide](https://openfate.ai/en/insights/true-solar-time)
- - [OpenFate llms.txt](https://openfate.ai/llms.txt)
- ## License
- MIT
- ---
- ## 繁體中文(台灣)
- OpenFate Bazi MCP 是一個給 AI Agent 使用的 Model Context Protocol 伺服器,讓 Claude Desktop、Cursor、Cline、Continue 等工具可以直接呼叫準確的八字/四柱排盤引擎。
- 本專案由 [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)。
- 這個 MCP 包裝了 OpenFate 的確定性計算套件:
- - `@openfate/bazi-engine`
- - `@openfate/true-solar-time`
- 目標很直接:不要讓大型語言模型自己亂算干支、節氣、真太陽時,而是把排盤交給可驗證的計算引擎。
- ## 為什麼需要這個 MCP
- 八字排盤不是文字推理題,而是確定性的曆法與時間計算。容易出錯的部分包括:
- - 二十四節氣邊界
- - 真太陽時
- - 經度與時區校正
- - 夏令時間偏移
- - 子時換日規則
- - 農曆轉公曆
- - 地支刑沖合害等互動
- 這個伺服器會回傳穩定 JSON,讓 AI 專心做說明、整理與解讀。
- ## 安裝
- 直接用 `npx` 執行:
- ```bash
- npx -y @openfate/bazi-mcp
- ```
- 如果 MCP client 支援 MCPB,或需要發布到 Smithery,可以建立完整的本機安裝 bundle:
- ```bash
- npm run mcpb:pack
- ```
- 可上傳的檔案會輸出到 `release/openfate-bazi-mcp-v<version>.mcpb`。
- 完成 `smithery auth login` 後,可發布這個本機 bundle 到 Smithery:
- ```bash
- npm run smithery:publish
- ```
- ## Claude Desktop 設定
- ```jsonc
- {
- "mcpServers": {
- "openfate-bazi": {
- "command": "npx",
- "args": ["-y", "@openfate/bazi-mcp"]
- }
- }
- }
- ```
- 如果 macOS 上 Claude Desktop 找不到 `npx`,可以改用絕對路徑:
- ```jsonc
- {
- "mcpServers": {
- "openfate-bazi": {
- "command": "/opt/homebrew/bin/npx",
- "args": ["-y", "@openfate/bazi-mcp"]
- }
- }
- }
- ```
- ## Cursor 設定
- ```jsonc
- {
- "mcpServers": {
- "openfate-bazi": {
- "command": "npx",
- "args": ["-y", "@openfate/bazi-mcp"]
- }
- }
- }
- ```
- ## Cline 設定
- ```jsonc
- {
- "mcpServers": {
- "openfate-bazi": {
- "command": "npx",
- "args": ["-y", "@openfate/bazi-mcp"],
- "disabled": false
- }
- }
- }
- ```
- ## Agent Skill
- 這個 repository 也包含一個可攜式 Agent Skill:
- ```txt
- skills/openfate-bazi/SKILL.md
- ```
- 當你希望 Claude、Claude Code、Codex、OpenClaw-style agent,或其他支援 `SKILL.md` 的工具記住如何正確使用 OpenFate Bazi MCP 時,可以使用這個 Skill。
- 如果要在 Claude Code workspace 使用,請把整個 skill folder 複製到:
- ```txt
- .claude/skills/openfate-bazi/
- ```
- 如果要做 Claude custom Skill,請把 `openfate-bazi` folder 壓成 zip,確保 `SKILL.md` 位於 folder root,再到 Claude 的 Skills 設定中上傳。
- ## 工具列表
- ### `calculate_bazi_chart`
- 計算確定性的八字命盤。
- 輸入欄位:
- - `year`
- - `month`
- - `day`
- - `hour`
- - `minute`
- - `second`
- - `gender`
- - `calendarType`
- - `isLeapMonth`
- - `longitude`
- - `timezone`
- - `timezoneId`
- - `dstOffset`
- - `enableTrueSolarTime`
- - `dayBoundaryMode`
- MCP 固定使用 `DAYUN_SECOND_V2`,呼叫端不能暗中切換起運規則。精確出生時間還要搭配
- `timezone` 或 `timezoneId`,並且只有 `chart.daYun.timing.status` 為 `CALCULATED`、版本為
- `DAYUN_SECOND_V2` 時才能呈現精確起運時間。`UNAVAILABLE` 會說明原因,原有起運欄位只作
- 明確標記的舊版 fallback。若要校正真太陽時,還應提供 `longitude`。
- ### `detect_bazi_interactions`
- 偵測本命盤及選填流年、大運地支的原始關係。
- 輸入欄位為 `yearBranch`、`monthBranch`、`dayBranch`,以及選填的 `hourBranch`、`annualBranch`、`dayunBranch`。出生時辰未知時省略 `hourBranch`,不會補入假設時柱。原有只傳流年的呼叫方式仍可使用。
- 支援類型:
- - 沖
- - 六合
- - 含旺支的半合(`COMBINATION_HALF`)
- - 三合
- - 三會
- - 刑
- - 破
- - 害
- 同一地支出現在不同柱位時,每個關係都會保留。例如申、寅、申、申會回傳三組不同柱位的寅申沖。流年與大運分別使用 `annual`、`dayun` 角色,即使地支相同,也不會與本命柱位合併。
- 半合口徑涵蓋申子、子辰、寅午、午戌、亥卯、卯未、巳酉、酉丑八組,每組都含子午卯酉其中一個旺支。申辰等兩端支不屬於此半合類型。三合齊全時,原始資料仍保留其中的半合關係。
- 每個關係包含穩定的 `id`,以及逐項對應的 `branches`、`pillars`。`targetElement` 只表示關係指向的五行,不代表已經合化。合類的 `transformationStatus` 為 `NOT_EVALUATED`,表示尚未評估合化,並非已成化或已判定不能化;其他關係使用 `NOT_APPLICABLE`。這些資料不是可直接累加的評分,也不會自動解沖;成立程度與解讀須由獨立分析層處理。
- 為相容既有 API,完整 `TRINE`、`DIRECTIONAL` 關係仍保留舊欄位 `resultElement`,值與 `targetElement` 相同,也僅表示五行指向。六合與半合不回傳 `resultElement`。
- ### `calculate_true_solar_time`
- 直接計算真太陽時。
- 當使用者問「為什麼 OpenFate 算出的時柱跟一般排盤網站不同」時,可以用這個工具說明差異。
- ### `reverse_bazi_to_solar_times`
- 用四柱八字反查可能的公曆時間。
- 範例輸入:
- ```txt
- 戊寅 己未 己卯 辛未
- ```
- 這是候選時間搜尋工具。最後仍應該用準確出生地經度、時區與真太陽時重新排盤。
- ### `get_openfate_bazi_policy`
- 回傳 OpenFate 的計算口徑:
- - 有出生地資料時,優先使用真太陽時。
- - 預設換日規則是 `ZI_HOUR_23`。
- - 如果出生證明時間包含夏令時間,應傳入 `dstOffset`。
- - 大運起運固定採用 `DAYUN_SECOND_V2`;只有計算成功的 timing receipt 才是精確起運時間。
- - 八字反查只能當候選搜尋,不能取代精準排盤。
- - 地支互動保留原始柱位關係,不代表加權分數或自動合化結果。
- ### `get_openfate_bazi_resources`
- 回傳 OpenFate 的官方連結,包括排盤、解讀、合盤、財富、真太陽時與 `llms.txt`。
- ## 回傳格式
- 回傳資料使用穩定、適合機器讀取的英文 key:
- ```jsonc
- {
- "data": {
- "chart": {},
- "policy": {}
- },
- "attribution": {
- "brand": "OpenFate.ai",
- "url": "https://openfate.ai",
- "engine": "@openfate/bazi-engine",
- "trueSolarTimeEngine": "@openfate/true-solar-time"
- }
- }
- ```
- 署名資訊會以一般資料欄位回傳,而不是藏在 `_meta`,方便 MCP client 或 AI 產生的圖表正確顯示來源。
- 排盤結果同時包含十神、藏干、納音、旬空、十二長生等柱位資料、版本化大運起運 receipt、標準化陽曆/農曆日期,以及實際採用的計算口徑。
- ## 開發
- ```bash
- npm install
- npm run build
- npm run smoke
- ```
- `smoke` 測試會啟動編譯後的 stdio server,並透過真正的 MCP SDK client 呼叫工具。
- 不編譯 `dist` 時可執行 `npm run smoke:source` 驗證原始碼。須具備相鄰的 `../bazi-engine` 原始碼工作目錄,且引擎與本套件都已安裝依賴。測試專用的 `tests/tsconfig.source.json` 將 `@openfate/bazi-engine` 指向該引擎的 `src/index.ts`;測試執行器會把設定傳給 MCP SDK 啟動的伺服器,並先驗證實際解析的原始碼路徑。這個模式不依賴修改過的已安裝引擎,在本套件重新執行 `npm ci --ignore-scripts` 後仍可重現。
- 兩種 smoke 模式使用相同 MCP 傳輸與回歸案例,涵蓋秒級起運、缺少起運輸入、重複地支、八組半合、未知時辰,以及流年/大運角色。一般 `smoke` 仍驗證編譯後 MCP 與已安裝的 npm 公開引擎。`npx tsc --noEmit -p tests/tsconfig.source.json` 可檢查協調中的原始碼契約,不產生編譯檔案。
- ### 引擎相容性
- 0.3 版需要 `@openfate/bazi-engine` 2.x。`DAYUN_SECOND_V2`、完整柱位關係與
- `dayunBranch` 契約皆由已編譯套件及協調原始碼兩種 smoke 模式驗證。正式發布的
- npm 依賴仍是版本來源;本套件不使用本機 `file:` 依賴。
- ## 隱私
- 這個套件不會回傳資料到 OpenFate 伺服器。所有計算都在本機 MCP subprocess 內完成。
- ## OpenFate 連結
- - [OpenFate.ai](https://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)
- - [OpenFate llms.txt](https://openfate.ai/llms.txt)
- ## 授權
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.