Yijing Bazi

You can run a specialized MCP server that analyzes I Ching hexagrams and performs BaZi (Chinese astrology) profiling and fortune forecasting. This server exposes a standard MCP interface so you can connect from AI clients and receive structured, culturally rich analyses and personalized guidance. It combines hexagram interpretation, BaZi chart generation, and integrated insights to support practical decision making and holistic consultations.

How to use

You connect your MCP client to the server using the built-in MCP protocol. The server is designed to be started locally or run in development and production modes, and it can be queried by compatible clients to generate hexagrams, interpret them, create BaZi charts, and receive combined analyses. Start the server in the mode that fits your workflow, then use your MCP client to send requests for hexagram generation, BaZi charts, or multi-tool analyses. The server returns structured results that you can present to users or feed into your AI assistant’s dialogue.

How to install

Prerequisites you need before installing are Node.js 18.0.0 or newer and the latest npm. The server runs on Windows, macOS, or Linux.

# Local installation in a project directory
# 1) Download or clone the project into a local folder
# 2) Install dependencies
npm install

# 3) Verify the installation works locally
node src/index.js --version

If you prefer a global install, you can install the server globally and run it from anywhere in your system.

# Global installation (recommended for quick starts)
npm install -g .

# Verify the installation and start the server in development mode (auto-restart)
npm run dev

# Start the server in production mode
npm start

You can also start the server directly from the local project files without the npm scripts by running the main entry point if you are developing or testing manually.

# Directly run the main entry (development/testing)
node src/index.js

Additional content

Client integration notes for MCP are included in your client configuration. Examples show how to wire the server into clients like Claude Desktop, Trae AI, Cursor IDE, and Cherry Studio, using either local commands or global/npx invocations. You can configure clients to start the server via an MCP command, or to connect to a locally running instance. If you use a local path, ensure your working directory contains the server so the client can spawn and connect to it.

Environment variables commonly referenced in configurations include LOG_LEVEL and NODE_ENV to control logging and environment modes. You may also enable caching and performance monitoring as needed.

If you plan to run in development mode, you can enable automatic restarts and live testing by using the development start command. For production deployments, use the production start command to ensure stable performance.

Troubleshooting tips cover common startup and path issues, including ensuring the correct Node.js version, reinstalling dependencies, and trying direct node execution if there are issues with package runners. Always check that the server process starts successfully and is reachable by your MCP client.

Available tools

yijing_generate_hexagram

Generate a hexagram using various methods like coin, yarrow, or time-based methods.

yijing_interpret

Interpret a hexagram with focus and detail level to provide hexagram readings.

yijing_advise

Provide practical decision guidance based on a hexagram and user question.

bazi_generate_chart

Create a BaZi chart from birth time, timezone, and gender.

bazi_analyze

Analyze a BaZi chart for ten gods, ten deities, and structure patterns.

bazi_forecast

Forecast fortunes across periods like fortune cycles, years, and months.

combined_analysis

Perform integrated analysis combining BaZi and hexagram information.

destiny_consult

Offer personalized destiny consultation based on birth info and questions.

knowledge_learn

Learn and query knowledge related to traditional Chinese astrology and I Ching.

case_study

Access and analyze practical cases across systems.