Open-source Basic Bazi MCP and Agent Skill

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 [email protected] 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", "[email protected]", "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.