# Zi Wei Dou Shu & BaZi Chinese Astrology MCP (`spyfree/mingli-mcp`) Actor

Chinese astrology MCP server and API for Zi Wei Dou Shu (紫微斗数) and BaZi (八字 / Four Pillars). Generate 12-palace star charts, fortune cycles, palace readings, Four Pillars, Ten Gods, and five-element analysis for AI agents.

- **URL**: https://apify.com/spyfree/mingli-mcp.md
- **Developed by:** [lee xin](https://apify.com/spyfree) (community)
- **Categories:** AI, MCP servers, Developer tools
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 mcp tool calls

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### Zi Wei Dou Shu and BaZi Chinese astrology MCP

Generate deterministic Chinese birth-chart data for AI agents through a hosted
Streamable HTTP MCP server. Mingli MCP combines Zi Wei Dou Shu (紫微斗数 / Purple
Star Astrology) and BaZi (八字 / Four Pillars of Destiny) in one endpoint. It is
designed for Claude, Cursor, VS Code, custom agents, and applications that need
structured calculations instead of an LLM inventing a chart from prose.

The service calculates 12-palace Zi Wei charts and stars, fortune periods,
palace details, Four Pillars, Ten Gods, hidden stems, and five-element balance.
Results can be returned as JSON or readable Markdown.

### What can this Chinese astrology MCP do?

| Tool | Result |
| --- | --- |
| `get_ziwei_chart` | Zi Wei Dou Shu chart with 12 palaces and star placements |
| `get_ziwei_fortune` | Decadal, yearly, monthly, daily, and hourly periods |
| `analyze_ziwei_palace` | Focused analysis of one palace and its stars |
| `get_bazi_chart` | Four Pillars, Ten Gods, hidden stems, and five elements |
| `get_bazi_fortune` | Simplified 10-year age-period marker and annual stem/branch |
| `analyze_bazi_element` | Element strength, balance, and missing elements |
| `list_fortune_systems` | Discover the implemented Zi Wei and BaZi systems |

Zi Wei palace and star terminology supports six locale codes: Simplified and
Traditional Chinese, English, Japanese, Korean, and Vietnamese. Some basic-info
keys remain Chinese. BaZi chart labels are currently primarily Chinese. Its
fortune tool reports a simplified 10-year age-period marker, not a full Da Yun
stem/branch sequence.

### Connect in 60 seconds

Use the Standby endpoint with your Apify API token:

```json
{
  "mcpServers": {
    "mingli": {
      "url": "https://spyfree--mingli-mcp.apify.actor/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_APIFY_TOKEN"
      }
    }
  }
}
```

Every client stores remote MCP configuration differently. Keep the token in the
client's secret storage and never commit it to source control.

Verify tool discovery without creating a paid event:

```bash
curl --request POST \
  --url https://spyfree--mingli-mcp.apify.actor/mcp \
  --header "Authorization: Bearer $APIFY_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

### BaZi Four Pillars API example

This successful `tools/call` creates one billable event:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_bazi_chart",
    "arguments": {
      "date": "1992-08-16",
      "time_index": 4,
      "gender": "女",
      "calendar": "solar",
      "format": "json"
    }
  }
}
```

Abridged real chart data:

```json
{
  "solar_date": "1992-08-16",
  "eight_char": "壬申 戊申 甲子 戊辰",
  "day_master": "甲",
  "wu_xing": {
    "scores": { "金": 2, "木": 1, "水": 2, "火": 0, "土": 3 }
  }
}
```

### Zi Wei Dou Shu API example

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "analyze_ziwei_palace",
    "arguments": {
      "birth_date": "1990-01-01",
      "time_index": 6,
      "gender": "男",
      "palace_name": "财帛宫",
      "calendar": "solar",
      "format": "markdown"
    }
  }
}
```

More copy-ready requests cover Zi Wei charts and fortune cycles, BaZi luck
cycles, five-element analysis, natural-language prompts, and real abridged
responses in the [complete Apify MCP guide](https://github.com/spyfree/mingli-mcp/blob/main/docs/APIFY_MCP_GUIDE.md).

### More tool call examples

Use each object as the `params` value of a `tools/call` request.

```json
{
  "name": "get_ziwei_chart",
  "arguments": {
    "date": "1990-01-01",
    "time_index": 6,
    "gender": "男",
    "calendar": "solar",
    "language": "en-US",
    "format": "json"
  }
}
```

```json
{
  "name": "get_ziwei_fortune",
  "arguments": {
    "birth_date": "1990-01-01",
    "time_index": 6,
    "gender": "男",
    "query_date": "2027-03-01",
    "format": "json"
  }
}
```

```json
{
  "name": "get_bazi_fortune",
  "arguments": {
    "birth_date": "1992-08-16",
    "time_index": 4,
    "gender": "女",
    "query_date": "2027-03-01",
    "format": "json"
  }
}
```

```json
{
  "name": "analyze_bazi_element",
  "arguments": {
    "birth_date": "1992-08-16",
    "time_index": 4,
    "gender": "女",
    "format": "json"
  }
}
```

### Input conventions and true solar time

`time_index` represents the traditional two-hour branch: `0` is early 子时,
`1` is 丑时, through `11` for 亥时; `12` is late 子时. Solar and lunar calendar
inputs are supported. The birth-chart tools also expose optional longitude,
precise birth hour/minute, and `use_solar_time` fields for true-solar-time
correction.

### Pricing

The current dollar amount is always shown in the Store Pricing tab.

- MCP initialization, `tools/list`, and other discovery requests do not create
  this Actor's paid event.
- Each successful `tools/call` creates one `tool-call` event.
- Invalid or failed tool calls are not charged by this Actor.
- If Apify cannot confirm the charge, the result is withheld and an MCP error is
  returned.

The Actor runs in Standby mode with a fixed 256 MB memory cap to keep hosting
costs low.

### Privacy, limitations, and responsible use

Birth dates, times, locations, and gender can be personal data. Send only data
you are authorized to process, avoid names and unrelated identifiers, and review
Apify's privacy and retention controls before production use. The application is
stateless and does not write charts to its own database, although the hosting
platform can retain operational metadata.

These calculations are for cultural study, software experimentation, and
entertainment. They do not make guaranteed predictions and must not replace
medical, legal, financial, employment, or other professional decisions.

For source code, self-hosting, and support, visit the
[GitHub repository](https://github.com/spyfree/mingli-mcp) or open a
[GitHub issue](https://github.com/spyfree/mingli-mcp/issues).

# Actor input Schema

## Actor input object example

```json
{}
```

# Actor output Schema

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("spyfree/mingli-mcp").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("spyfree/mingli-mcp").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call spyfree/mingli-mcp --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,spyfree/mingli-mcp"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/WduXGtWS9b7d2bPIV/builds/m0NOo5u52qH0MBeSV/openapi.json