Purpose
OpenFate Bazi MCP is a Model Context Protocol (MCP) server for accurate Bazi/Four Pillars chart casting in AI Agents (such as Claude Desktop, Cursor, Cline, Continue). Its core purpose is to let language models call a reliable calculation engine rather than performing calendar mathematics themselves, avoiding errors the model may produce in deterministic calculations such as solar term boundaries, true solar time, and day-change rules.
Main Capabilities
This MCP wraps OpenFate's deterministic calculation packages: @openfate/bazi-engine and @openfate/true-solar-time. The tools provided include:
- calculate_bazi_chart: Calculates a deterministic Bazi chart. Supports parameters such as enableTrueSolarTime and dayBoundaryMode. The luck pillar start strategy is fixed to DAYUN_SECOND_V2, and callers cannot switch the rule. You must pass an exact birth time plus timezone or timezoneId to obtain a calculation receipt; the exact luck pillar start time is only presented when chart.daYun.timing.status is CALCULATED and the version is DAYUN_SECOND_V2. UNAVAILABLE will explain the reason and mark the retained legacy scalar fields as fallback values. Passing longitude enables true solar time correction.
- detect_bazi_interactions: Detects the raw relationships of the natal chart and optional annual and luck pillar earthly branches. The inputs are yearBranch, monthBranch, dayBranch, and optionally hourBranch, annualBranch, dayunBranch. When the birth hour is unknown, omit hourBranch; no assumed hour pillar will be inserted. Supports types such as six combinations and half combinations containing the prosperous branch (COMBINATION_HALF). Every occurrence at each matching pillar position is retained; for example, Shen, Yin, Shen, Shen will return three different Yin-Shen clashes. Half combinations cover the eight groups Shen-Zi, Zi-Chen, Yin-Wu, Wu-Xu, Hai-Mao, Mao-Wei, Si-You, and You-Chou. Each relationship has a stable id and corresponding branches and pillars arrays. targetElement indicates the element the relationship points to, and does not mean transformation has occurred; for combination types, transformationStatus is NOT_EVALUATED. These results are not scoring weights, and they do not automatically resolve clashes.
- calculate_true_solar_time: Directly calculates true solar time, which can be used to explain why the hour pillar differs from ordinary clock tools.
- reverse_bazi_to_solar_times: Looks up possible Gregorian times from the Four Pillars Bazi. This is a candidate search tool, and the final result still needs to be recast using accurate longitude, timezone, and true solar time.
- get_openfate_bazi_policy: Returns OpenFate's calculation conventions, including prioritizing true solar time, the default day-change rule ZI_HOUR_23, passing dstOffset during daylight saving time, fixed DAYUN_SECOND_V2 for luck pillar start, reverse lookup being only for candidate search, and retaining raw pillar position relationships for earthly branch interactions.
- get_openfate_bazi_resources: Returns OpenFate official links, including chart casting, interpretation, synastry, wealth, true solar time, and llms.txt.
Chart results include pillar data such as Ten Gods, hidden stems, Nayin, Xun Kong, and Twelve Stages, versioned luck pillar start receipts, standardized solar/lunar dates, and the calculation conventions actually adopted. Attribution information is returned as ordinary data fields rather than hidden in _meta.
Usage
It can be run via npx. For MCPB-compatible clients and Smithery, a self-contained local bundle can be built, and the upload-ready artifact is written to release/openfate-bazi-mcp-v<version>.mcpb. After completing smithery auth login, this local bundle can be published to Smithery. If Claude Desktop on macOS cannot find npx, an absolute path can be used. The repository also includes a portable Agent Skill, suitable for Claude, Claude Code, Codex, OpenClaw-style agents, or other tools compatible with SKILL.md; when used in a Claude Code workspace, copy the skill folder to the specified location; for a Claude custom Skill, compress the openfate-bazi folder into a zip, ensuring that SKILL.md is at the root of the folder before uploadingPassed on.
Applicable Scenarios
Suitable for scenarios that require accurate Bazi chart calculation, true solar time correction, earthly branch relationship detection, or reverse lookup of the four pillars within an AI Agent, and is especially suitable for avoiding errors caused by the LLM deriving the calendar on its own.
Limitations
The fortune period starting strategy is fixed to DAYUN_SECOND_V2, and callers cannot switch it. The precise fortune period start time is presented only when timing.status is CALCULATED and the version matches. Reverse lookup results are candidates only and cannot replace precise chart calculation. Earthly branch interaction results do not represent weighted scores or automatic combination and transformation. Version 0.3 requires @openfate/bazi-engine 2.x. Calculations are completed within the local MCP subprocess, and data is not sent back to the OpenFate server.
