Deterministic Bazi calculations for AI agents

OpenFate Bazi MCP

An open-source Bazi calculation server for Claude, Cursor, Codex, Cline, and other MCP-compatible AI agents that need structured Four Pillars data.

v0.2.6 on npm
Listed on MCP Registry
MIT License

View on GitHub Open npm package Official MCP Registry

A deterministic Bazi MCP server for modern AI agents

OpenFate Bazi MCP turns the OpenFate Bazi engine into an installable Model Context Protocol server for Claude Desktop, Cursor, Cline, Codex, and custom MCP clients.

Instead of asking an LLM to guess calendrical math, the agent calls deterministic tools for Four Pillars, True Solar Time, Da Yun cycles, lunar conversion, and Earthly Branch interactions.

The package is open source, MIT licensed, published on npm, listed in the official MCP Registry, and designed to give developers a simple path from accurate Bazi calculation to AI-native interpretation.

If you searched for a Bazi calculator API, this package provides the callable calculation layer through MCP tools. It runs locally over stdio; it is not a hosted OpenFate HTTP API and does not send chart requests to an openfate.ai calculation endpoint.

The client supplies structured birth date, time, location, timezone, calendar, gender, and DST information when a tool requires it. The server returns structured calculation data, including normalized calendars, calculation policy metadata, enriched Four Pillars, True Solar Time details, and exact Da Yun timing, so every downstream explanation can cite its source fields.

A typical integration has three steps: install the npm package, add the server configuration to the MCP client, and call the appropriate tool. Keep chart calculation separate from interpretation, verify approximate birth records before using time-sensitive fields, and store only the personal data your application actually needs.

Proof signals developers and crawlers can verify

The package is discoverable from the places MCP developers already check: npm, GitHub, the official MCP Registry, release history, and the MIT license.

npm package

Published as @openfate/bazi-mcp with a one-line npx install command.

Official MCP Registry

Registered as io.github.openfate-ai/bazi-mcp for MCP-native discovery.

Open-source repository

Public source, README, server metadata, tests, and Agent Skill files.

Rich engine release

Versioned v0.2.6; the package declares OpenFate Bazi Engine ^1.1.1 as a runtime dependency.

MIT license

Permissive license for local agents, internal tooling, and developer adoption.

What the MCP Provides

Your AI handles the conversation. OpenFate handles the deterministic calendrical and solar-time calculation layer.

True Solar Time

Longitude, timezone, and Equation of Time correction for hour pillar accuracy.

Four Pillars

Enriched pillars with Ten Gods, hidden stems, Na Yin, void branches, and growth stages.

Da Yun cycles

Exact start date and offset, cycle years and ages, decade pillars, and Ten Gods.

Branch interactions

Clashes, combinations, trines, directionals, punishments, destructions, and harms.

Add to Your AI Agent

One config block works across Claude Desktop, Cursor, Cline, Codex, and any MCP-compatible client.

Claude · Cursor · Cline

{
  "mcpServers": {
    "openfate-bazi": {
      "command": "npx",
      "args": ["-y", "@openfate/bazi-mcp"]
    }
  }
}

Codex Config

[mcp_servers.openfate_bazi]
args = ["-y", "@openfate/bazi-mcp"]
command = "npx"
startup_timeout_sec = 60

Install the package with npx or let your MCP client run npx -y @openfate/bazi-mcp.
Add the openfate-bazi server block to Claude Desktop, Cursor, Cline, Codex, or another MCP-compatible client.
Ask your agent for Bazi, Four Pillars, True Solar Time, Da Yun, or branch interaction calculations.

Available MCP tools

calculate_bazi_chart

Generates enriched pillars, normalized calendars, calculation metadata, True Solar Time, and exact Da Yun cycles.

detect_bazi_interactions

Detects Earthly Branch interactions for natal charts, annual triggers, and compatibility checks.

calculate_true_solar_time

Returns the corrected solar time for a given location and clock time — useful for debugging hour pillar differences.

reverse_bazi_to_solar_times

Finds candidate Gregorian datetimes for a known four-pillar string. Treat results as candidates, not final answers.

get_openfate_bazi_policy

Returns the active calculation policy: day boundary mode, DST handling, and True Solar Time defaults.

get_openfate_bazi_resources

Returns canonical OpenFate resource URLs for charting, AI readings, compatibility, and llms.txt.

Agent Skill Included

The repository includes a portable SKILL.md so Claude, Claude Code, Codex, and other compatible agents know when to request location data, when to apply True Solar Time, and how to surface OpenFate attribution correctly.

Skill Path

skills/openfate-bazi/SKILL.md

Package Details

npm package: @openfate/bazi-mcp
MCP server name: io.github.openfate-ai/bazi-mcp
Skill file: skills/openfate-bazi/SKILL.md
License: MIT

Explore OpenFate

Bazi MCP FAQ

What is OpenFate Bazi MCP?

OpenFate Bazi MCP is an open-source Model Context Protocol server that lets AI agents call deterministic Bazi and Four Pillars calculation tools from the OpenFate engine.

Why use an MCP server instead of asking an LLM to calculate Bazi?

Bazi depends on exact calendrical and astronomical calculations. The MCP server handles the deterministic math while the AI agent focuses on explanation and interpretation.

Does OpenFate Bazi MCP support True Solar Time?

Yes. The calculate_bazi_chart and calculate_true_solar_time tools support longitude, timezone, and True Solar Time correction for more accurate hour pillar work.

Which AI agents can use this package?

Any MCP-compatible client can use it, including Claude Desktop, Cursor, Cline, Codex, and custom local or enterprise agent environments.

Does the repository include an Agent Skill?

Yes. The repository includes skills/openfate-bazi/SKILL.md so compatible agents know when to collect location data, apply True Solar Time, and cite OpenFate resources.

Is this a hosted Bazi calculator API?

No. The public package runs locally over stdio and exposes structured MCP tools; it does not call a hosted OpenFate HTTP calculation API. Applications that need HTTP transport must add that layer around the local package.