freebazi-mcp is a Model Context Protocol (MCP) server for calculating a complete Chinese BaZi (Four Pillars) chart from birth date, time, and place. It wraps the same calculation engine as freebazi.com: fully offline, corrects for true solar time and historical daylight saving time, and is cross-validated word-for-word against mainstream BaZi libraries. No API key, no network calls, everything runs locally. Requires Node.js 18+.
Purpose: To provide an MCP tool interface for BaZi chart casting, enabling AI agents or MCP-capable clients to directly calculate and obtain BaZi chart information, suitable for applications or conversation scenarios that need to integrate BaZi analysis capabilities.
Main capabilities:
- Four Pillars (year, month, day, hour), each pillar containing a Heavenly Stem and an Earthly Branch.
- The Day Stem (Day Master) and the Ten Gods for each character.
- Hidden Stems, Na Yin, and the Twelve Stages of Life.
- Five Elements distribution (including visible Five Elements and Five Elements including hidden stems).
- Shen Sha and Earthly Branch relationships (combinations, clashes, punishments, harms).
- Major Luck Cycles (fortune pillars) with the current cycle marked, as well as the current year's Annual Pillar.
- Returns a link to the full interactive chart on freebazi.com.
- Includes a search_cities tool that can search about 490 major world cities by English or Chinese name, returning the country, longitude, and IANA time zone for each match, making it easy to pass an exact city to compute_bazi_chart.
Usage: Can be run directly via npx. To configure it for Claude Desktop, add it to claude_desktop_config.json, providing the command and arguments. Other MCP clients (such as Cline, Continue, Cursor, etc.) use the same command/argument format. The main tool is compute_bazi_chart, with parameters including birth date, time, and city, among others; refer to the project documentation for the specific parameters.
For example: calculate the BaZi chart for someone born on June 15, 1990 at 9:30 AM in New York. The server will resolve New York, apply true solar time (9:30 AM becomes 8:34 AM, 56 minutes earlier, thereby changing the hour pillar), and return the Four Pillars 庚午 壬午 辛亥 壬辰, with the Day Master being 辛 (Yin Metal), as well as all Ten Gods, Five Elements, Major Luck Cycles, and other information.
Applicable scenarios: Suitable for developers, researchers, or enthusiasts who want to obtain BaZi chart results programmatically or through an AI assistant. It can be usedfor personal BaZi analysis, learning BaZi knowledge (the project page provides an interactive calculator, guides, and a link to the full chart on freebazi.com, as well as explanation pages about what BaZi is, how a chart is constructed, the Five Elements, the Day Master, the Ten Gods, etc.), or integration into applications that need chart calculation capabilities.
Limitations:
- Requires Node.js 18+.
- The tool only describes the chart; it does not predict specific events. BaZi is a traditional framework for reflecting on personality, tendencies, and timing.
- Solar term boundaries are calculated based on the apparent solar longitude and standard astronomical formulas, and time zones (including historical daylight saving time) are resolved from the IANA database. The engine's Four Pillars results match mainstream libraries word-for-word across thousands of test charts.
- City data comes from GeoNames (CC BY 4.0). Simplified to Traditional conversion is via OpenCC.
- Other features and pricing information are not yet provided.
