yijing-bazi

This MCP server provides a dedicated Chinese metaphysics analysis capability combining Yiijing (I Ching) hexagram analysis with BaZi (Four Pillars of Destiny) astrology. It exposes a set of tools for generating and interpreting hexagrams, analyzing birth charts, and performing integrated destiny consultations. Clients can access these capabilities through the MCP protocol, enabling AI assistants to request hexagram results, BaZi charts, and cross-domain insights in a structured way. Typical workflows involve asking questions to generate hexagrams, obtaining interpretations, then running BaZi calculations and combining the results for personalized guidance. The server is designed to be easily accessible via MCP clients like Claude Desktop, Trae AI, or Cherry Studio, and supports run modes for development and production.

To use it, install the MCP server via npx (or install locally if you maintain a copy of the project), then start the server in MCP mode. When a client communicates, you can invoke tools such as yijing_generate_hexagram, yijing_interpret, yijing_advise, bazi_generate_chart, bazi_analyze, bazi_forecast, and combined_analysis to obtain results. The integrated knowledge and case libraries help refine responses, enabling more personalized guidance based on the user’s question and context.

Prerequisites:

• Node.js 18.x or higher
• npm (comes with Node.js)
• Access to the internet to install packages from npm

Installation steps (local development workflow):

# 1) Ensure Node.js and npm are installed
node -v
npm -v

# 2) Clone or download the yijing-bazi-mcp repository
# If you already have the project, navigate to its directory
cd path/to/yijing-bazi-mcp

# 3) Install dependencies
npm install

# 4) Verify the MCP server build (optional)
node src/index.js --version

Running in development or production mode:

# 5) Development mode (auto-reload if configured)
npm run dev

# 6) Production mode
npm start

If you prefer a quick test without local install, you can also run the MCP server via npx directly from npm as shown in the mcp_config example.

Tips and common considerations:

• Ensure Node.js version compatibility (18.x+ is recommended).
• When using Claude Desktop or similar clients, update claude_desktop_config.json to point to the MCP server (the example uses npx with yijing-bazi-mcp@latest).
• If you encounter issues starting the server with npx, you can run the server locally via node src/index.js to verify basic functionality before packaging for MCP access.
• Environment variables like LOG_LEVEL and NODE_ENV shape logging and mode; set them according to your deployment (production for live use, development for testing).
• If you switch to a local project workflow, you may need to adjust the cwd in your MCP configuration to the absolute path of your project directory.
• Common MCP issues often relate to tooling wrappers (npx, npm exec) and path resolution; if you see errors about executable resolution, try using npm exec or switch to a direct node command as a troubleshooting step.