Mingli

You can run Mingli MCP Server to provide multiple fortune-telling systems through the MCP protocol, then connect with tools like Cursor or Claude Code to generate charts, analyze palaces, and query fortunes in your preferred language. This server emphasizes easy setup, multiple transport options, and extensible system support so you can add new fortune-telling methods with minimal effort.

How to use

Connect to Mingli MCP Server using an MCP client that supports the standard MCP protocol. You can run the server locally and expose it via stdio or over HTTP, then configure your client to connect using the corresponding method.

Practical usage patterns include: starting the local server and issuing requests to generate a Ziwei盘 (Ziwei chart), fetch fortune information, analyze specific palaces, list available fortune systems, or work with Bazi (Four Pillars) charts. You can also switch output language to your preferred locale such as zh-CN (Simplified Chinese) or en-US (English).

Typical workflow after the server is running: 1) choose a fortune-telling system, 2) provide birth information (date, time, gender, calendar), 3) request a chart or fortune, 4) review the formatted output in JSON or Markdown depending on the request.

How to install

Prerequisites you need before installing: a supported runtime (Python for source installations), and the option to run a runtime environment like uvx or Docker for easier deployment.

Option A: Install using uvx (recommended) and run locally. Create or update your MCP configuration to point to the stdio server provided by the package. Use the following configuration snippet in your MCP setup.

{
  "mcpServers": {
    "mingli": {
      "command": "uvx",
      "args": ["mingli-mcp"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Option B: Install using Docker

If you prefer containerized deployment, download the Docker Compose file and start the service, then connect via HTTP as the MCP endpoint.

# Download and start the service
mkdir -p /opt/mingli-mcp
cd /opt/mingli-mcp
wget https://raw.githubusercontent.com/spyfree/mingli-mcp/main/docker-compose.yml

# Start the service in detached mode
docker-compose up -d

Option C: Install from source

If you need to customize or contribute to the server, you can install from source. This path requires Python 3.8+ and a supported IDE or MCP client.

# 1) Clone the project
git clone https://example.com/spyfree/mingli-mcp.git
cd mingli-mcp

# 2) Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# 3) Install dependencies for stdio mode (recommended) or full HTTP support
pip install -r requirements.txt
# or for HTTP support
pip install -r requirements-http.txt
# or: pip install .[http]

# 4) Optional: copy example config and edit
cp examples/config/.env.example .env

# 5) Run the server
python mingli_mcp.py

Configuration and usage notes

Environment variables control behavior and language defaults. You can set them per-MCP server, per project, or as system environment variables.

{
  "mcpServers": {
    "mingli": {
      "command": "/path/to/python",
      "args": ["mingli_mcp.py"],
      "env": {
        "LOG_LEVEL": "INFO",
        "DEFAULT_LANGUAGE": "zh-CN"
      }
    }
  }
}

Security and notes

Only expose the MCP endpoint to trusted clients. Use HTTP API keys if you enable HTTP transport to restrict access. When using stdio, ensure only authorized tools connect to the local MCP process.

Tools and endpoints overview

Mingli MCP Server provides a collection of fortune-telling tools including Ziwei chart generation, Ziwei fortune queries, palace analysis, and Bazi chart and fortune analysis. You can request multiple endpoints from a single birth record, including detailed five-element analysis and missing element recommendations.

Available tools

get_ziwei_chart

Fetches complete Ziwei (Purple Star) chart information including twelve palaces, main stars, auxiliary stars, miscellaneous stars, and Four Transformations.

get_ziwei_fortune

Retrieves fortune information for Ziwei chart based on birth data and query date.

analyze_ziwei_palace

Analyzes a specific Ziwei palace and its星曜 configuration for deeper interpretation.

list_fortune_systems

Lists all available fortune-telling systems supported by the server.

get_bazi_chart

Generates Four Pillars (BaZi) chart information including stems, branches, and ten Gods.

get_bazi_fortune

Provides fortune information based on BaZi data, including age cycles and annual influence.

analyze_bazi_element

Analyzes the strength and balance of the Five Elements in a BaZi chart.