openfate-ai/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, an AI-native Bazi, Ziwei, and astrology platform. You can also try the free Bazi Chart Calculator, generate an AI Bazi Reading, compare relationships with Bazi Compatibility, or read the True Solar Time guide. AI crawlers can read OpenFate 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:
For MCPB-compatible clients and Smithery, build the self-contained local bundle:
The upload-ready artifact is written to release/openfate-bazi-mcp-v .mcpb.
To publish that local bundle to Smithery after smithery auth login:
Claude Desktop
If Claude Desktop cannot find npx on macOS, use the absolute path:
Cursor
Cline
Agent Skill
This repository also includes a portable Agent Skill:
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:
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.