OPEN SOURCE · DETERMINISTIC CHARTING · LOCAL FIRST

Open-source Basic Bazi MCP and Agent Skill

AI agents can verify basic chart facts through one versioned deterministic core. Calculations run locally without uploading birth input.

Open source · MCP · Agent Skill

Bring Yuanzi Zhiyi charting to your AI assistant

Calculate Four Pillars, Ten Gods and element counts locally, with true solar time and explicit day boundaries. Get structured facts and a clear chart image in one call.

npx -y yuanzi-bazi-agent-kit@0.3.0 mcp

npm v0.3.0 Listed in MCP Registry

View GitHub

Local rendering · No API key · MIT open source

Example Bazi chart with Four Pillars, Ten Gods, hidden stems and unweighted element counts — Illustrative chart · No customer data

Basic charting for your AI assistant

Calculate Four Pillars, the day master, Ten Gods, hidden stems and unweighted element counts. Use solar or lunar dates, time zones, true solar time and explicit day boundaries. Calculation and image rendering run locally, without an API key. Unknown hours remain unknown.

One call returns both JSON and a chart PNG. The image follows the main site's paper and pillar design. Inline display depends on your client; the Skill can also provide a local image file.

Install with npm

View the npm package. Start the MCP server with the command below. The first run downloads dependencies; chart calculation and image rendering then run locally:

npx -y yuanzi-bazi-agent-kit@0.3.0 mcp

Build from source

Requires Node.js 22.19 or newer. The current npm version is 0.3.0; the GitHub source version is 0.3.0. Build from source to generate the updated example charts.

git clone https://github.com/yuanzizhiyi/yuanzi-bazi-agent-kit.git
cd yuanzi-bazi-agent-kit
npm ci
npm run build

Connect MCP or the Skill

Add this configuration to a client supporting local stdio MCP. Use the published npm package:

{
  "mcpServers": {
    "yuanzi-bazi": {
      "command": "npx",
      "args": ["-y", "yuanzi-bazi-agent-kit@0.3.0", "mcp"]
    }
  }
}

For Skill use, install the repository as a Skill in a compatible agent, using SKILL.md as the entry point. Keep the built dist/, dependencies and assets/. The Skill obtains JSON and PNG through the CLI; for manual use, append --image chart.png with an unused file path.

Learn more

Full setup and input examples · Calculation method · Validation cases

Developer interfaces: calculate_basic_bazi_chart returns the chart; get_yuanzi_bazi_capabilities returns a hosted feature link on request. The JSON contract remains yuanzi-basic-bazi/v1. See repository documentation for the site's WebMCP integration.

The public core excludes luck cycles, compatibility and AI readings. Code uses MIT licensing; the bundled font has its own open-source license. Brand trademarks are not included in the code license.