Chinese Astrology MCP Server — Zi Wei Dou Shu & BaZi

Mingli MCP is a deterministic Chinese astrology server for AI agents and MCP clients. It generates Zi Wei Dou Shu (紫微斗数 / Purple Star Astrology) and Bazi (八字 / Four Pillars of Destiny) charts from structured birth data, including the 12 palaces, stars, Four Pillars, Ten Gods, five elements, fortune periods, and date-based analysis.

中文简介： 一个面向 AI 工具的开源命理 MCP 服务，支持紫微斗数排盘、八字排盘、 宫位与五行分析，以及大限、流年、流月、流日和流时查询。

Apify hosted endpoint

The hosted Actor runs as a 256 MB Standby MCP server. It can be connected to Claude, Cursor, VS Code, custom agents, or any client that supports remote Streamable HTTP MCP. Until the Actor is published in Apify Store, the endpoint is available only to users who have been granted access.

• MCP endpoint: https://spyfree--mingli-mcp.apify.actor/mcp

• Authentication: Authorization: Bearer YOUR_APIFY_TOKEN

• Billing: tool discovery is free; each successful tools/call is one tool-call event

• Detailed setup and copy-ready examples: Apify MCP guide

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

Example questions for an AI client:

• “Generate my Zi Wei Dou Shu birth chart for 1990-01-01, 午时, male.”

• “排一个 1992-08-16 辰时出生的女命八字，并分析五行强弱。”

• “分析这个紫微命盘的财帛宫，并说明主要星曜配置。”

• “Compare the five-element balance of these two Bazi charts.”

This project provides deterministic calendar and chart calculations for cultural, educational, and entertainment use. It is not medical, legal, financial, or other professional advice.

Related MCP server: mcp-luopan

What this Chinese astrology MCP can do

Unlike a generic LLM response, the tools first calculate a structured chart from calendar inputs and then return consistent JSON or Markdown. The same schemas can be used in chat, an automated workflow, or a custom Chinese astrology application.

✨ 特性

🎯 核心特性

• ✅ 多命理系统支持: 采用插件化架构，轻松扩展新的命理系统

  • ✅ 紫微斗数（已实现）

  • ✅ 八字（已实现）⭐ 新增

  • 🔄 西方占星（预留接口）

• ✅ 多语言支持: 紫微斗数宫位与星曜术语支持6种语言；八字核心标签目前以中文为主

  • 🇨🇳 简体中文 (zh-CN)

  • 🇹🇼 繁体中文 (zh-TW)

  • 🇺🇸 English (en-US)

  • 🇯🇵 日本語 (ja-JP)

  • 🇰🇷 한국어 (ko-KR)

  • 🇻🇳 Tiếng Việt (vi-VN)

• ✅ 多传输方式: 支持stdio、HTTP、WebSocket等多种传输协议

• ✅ MCP标准兼容: 完全兼容 MCP 协议规范

• ✅ 易于扩展: 清晰的抽象层设计，添加新系统只需3步

🔮 紫微斗数功能

• ✅ 完整排盘: 十二宫、主星、辅星、杂耀、四化等

• ✅ 运势查询: 大限、流年、流月、流日、流时

• ✅ 宫位分析: 深度分析特定宫位的星曜配置

• ✅ 多种历法: 支持阳历和农历输入

• ✅ 格式化输出: JSON和Markdown两种输出格式

• ⭐ 真太阳时: 支持按出生地经度和精确时间修正 新功能

🎴 八字功能 ⭐ 新增

• ✅ 四柱排盘: 年月日时四柱、天干地支详细信息

• ✅ 十神分析: 比肩、劫财、食神、伤官、偏财、正财、七杀、正官、偏印、正印

• ✅ 五行分析: 金木水火土分数、百分比、平衡度

• ✅ 地支藏干: 详细的地支藏干信息

• ✅ 运势查询: 简化十年年龄段标记、流年干支分析

• ✅ 缺失分析: 自动识别五行缺失并给出建议

• ✅ 多种历法: 支持阳历和农历输入

• ⭐ 真太阳时: 支持按出生地经度和精确时间修正 新功能

📚 文档导航

新用户推荐阅读路径：

1. 快速开始指南 ⭐ - 5分钟快速上手

   • 安装方法（uvx、pip、Docker）

   • IDE配置示例

   • 第一次排盘体验

2. 用户指南 - 完整功能说明

   • 所有工具详解

   • 参数说明

   • 输出格式对比

   • 使用限制

3. 真太阳时使用指南 ⭐ - 精确时辰修正（新功能）

   • 200+全球城市支持

   • 自动时辰修正

   • 适用于西北地区

4. API使用示例 - 17个实用代码示例

   • 基础用法

   • 紫微斗数、八字示例

   • 高级模式（批量处理、错误处理）

5. Apify MCP 使用指南 - 托管版接入与示例

   • Claude、Cursor 与通用 MCP 客户端配置

   • curl / JSON-RPC 调用示例

   • 计费、隐私与常见问题

6. 故障排查指南 - 16个常见问题解决方案

   • 安装问题

   • 配置问题

   • 运行时错误

   • 调试技巧

开发者文档：

• CLAUDE.md - Claude Code开发指南

• 更多文档 - 完整文档索引

📋 可用工具

1. get_ziwei_chart

获取紫微斗数完整排盘信息

参数:

• date (string, 必需): 出生日期 YYYY-MM-DD，如 "2000-08-16"

• time_index (integer, 必需): 时辰序号 0-12

  • 0=早子时(23-01), 1=丑时(01-03), 2=寅时(03-05), 3=卯时(05-07)

  • 4=辰时(07-09), 5=巳时(09-11), 6=午时(11-13), 7=未时(13-15)

  • 8=申时(15-17), 9=酉时(17-19), 10=戌时(19-21), 11=亥时(21-23)

  • 12=晚子时(23-01)

• gender (string, 必需): 性别 "男" 或 "女"

• calendar (string, 可选): 历法 "solar"(阳历) 或 "lunar"(农历), 默认 "solar"

• is_leap_month (boolean, 可选): 是否闰月，默认 false

• format (string, 可选): 输出格式 "json" 或 "markdown", 默认 "markdown"

• language (string, 可选): 输出语言，可选 "zh-CN", "zh-TW", "en-US", "ja-JP", "ko-KR", "vi-VN"，默认 "zh-CN" ⭐ 新增

示例:

{
  "date": "2000-08-16",
  "time_index": 2,
  "gender": "女",
  "calendar": "solar"
}

2. get_ziwei_fortune

获取紫微斗数运势信息

参数:

• birth_date (string, 必需): 出生日期

• time_index (integer, 必需): 时辰序号

• gender (string, 必需): 性别

• calendar (string, 可选): 历法类型

• query_date (string, 可选): 查询日期，不填则为今天

• format (string, 可选): 输出格式

• language (string, 可选): 输出语言，默认 "zh-CN" ⭐ 新增

3. analyze_ziwei_palace

分析紫微斗数特定宫位

参数:

• birth_date (string, 必需): 出生日期

• time_index (integer, 必需): 时辰序号

• gender (string, 必需): 性别

• palace_name (string, 必需): 宫位名称，可选值：

  • 命宫、兄弟、夫妻、子女、财帛、疾厄

  • 迁移、仆役、官禄、田宅、福德、父母

• calendar (string, 可选): 历法类型

• format (string, 可选): 输出格式

• language (string, 可选): 输出语言，默认 "zh-CN" ⭐ 新增

4. list_fortune_systems

列出所有可用的命理系统

5. get_bazi_chart ⭐ 新增

获取八字（四柱）排盘信息

参数:

• date (string, 必需): 出生日期 YYYY-MM-DD

• time_index (integer, 必需): 时辰序号 0-12

• gender (string, 必需): 性别 "男" 或 "女"

• calendar (string, 可选): 历法 "solar"(阳历) 或 "lunar"(农历), 默认 "solar"

• is_leap_month (boolean, 可选): 是否闰月，默认 false

• format (string, 可选): 输出格式 "json" 或 "markdown", 默认 "markdown"

示例:

{
  "date": "2000-08-16",
  "time_index": 2,
  "gender": "女"
}

输出包含:

• 四柱八字（年月日时）

• 天干地支详细信息

• 十神分析（比肩、劫财等）

• 五行分数统计

• 地支藏干信息

• 生肖、日主等基本信息

6. get_bazi_fortune ⭐ 新增

获取八字运势信息

参数:

• birth_date (string, 必需): 出生日期

• time_index (integer, 必需): 时辰序号

• gender (string, 必需): 性别

• calendar (string, 可选): 历法类型

• query_date (string, 可选): 查询日期，不填则为今天

• format (string, 可选): 输出格式

输出包含:

• 当前年龄

• 简化十年年龄段信息（非完整大运干支推演）

• 流年信息（年份、干支、生肖）

• 本命八字

7. analyze_bazi_element ⭐ 新增

分析八字五行强弱

参数:

• birth_date (string, 必需): 出生日期

• time_index (integer, 必需): 时辰序号

• gender (string, 必需): 性别

• calendar (string, 可选): 历法类型

• format (string, 可选): 输出格式

输出包含:

• 日主及其五行属性

• 五行分数和百分比

• 最旺/最弱五行

• 缺失五行

• 平衡度评价

• 补救建议

🚀 快速开始

在线体验

• Apify 托管 MCP: https://spyfree--mingli-mcp.apify.actor/mcp（需要 Apify token）

• Smithery 部署: https://server.smithery.ai/@spyfree/mingli-mcp/mcp

• 添加到 Cursor:

• 添加到 Claude Code: claude mcp add mingli -- uvx mingli-mcp

• 添加到 OpenAI CodeX: codex mcp add mingli -- uvx mingli-mcp

📦 安装方式

方式1: uvx (推荐)

使用 uvx 是最简单的安装方式，无需手动管理依赖：

在 ~/.cursor/mcp.json 或对应IDE的MCP配置文件中添加：

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

方式2: Docker

使用 Docker 部署，适合服务器环境或需要隔离的场景：

# 下载配置文件
mkdir -p /opt/mingli-mcp
cd /opt/mingli-mcp
wget https://raw.githubusercontent.com/spyfree/mingli-mcp/main/docker-compose.yml

# 启动服务
docker-compose up -d

然后在MCP配置中使用HTTP连接：

{
  "mcpServers": {
    "mingli": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

方式3: 从源码安装

适合开发者或需要自定义的场景：

🛠️ 从源码安装

环境要求

• Python 3.8+

• Cursor IDE 或其他支持MCP的工具

1. 克隆项目

cd /Users/lix18854/Documents/code
# 项目已在 ziwei_mcp 目录中
cd ziwei_mcp

2. 创建虚拟环境（推荐）

python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# 或
venv\Scripts\activate  # Windows

3. 安装依赖

基础安装（stdio模式，推荐）

pip install -r requirements.txt

或完整安装（包含HTTP传输支持）

pip install -r requirements-http.txt
# 或使用 pip install .[http]

注意: stdio模式无需任何额外配置即可使用，推荐日常使用。HTTP模式仅在需要Docker部署或服务器环境时使用。

4. 配置环境变量（可选）

cp examples/config/.env.example .env
# 编辑 .env 文件根据需要调整配置

5. 测试运行

python -m mingli_mcp

6. 配置 Cursor MCP

编辑或创建 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mingli": {
      "command": "/Users/lix18854/Documents/code/ziwei_mcp/venv/bin/python",
      "args": ["-m", "mingli_mcp"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

注意: 请根据实际路径调整 command 和 args

7. 重启 Cursor

重启 Cursor IDE 以加载新的 MCP 配置。

📁 项目结构

ziwei_mcp/
├── pyproject.toml             # 项目配置
├── requirements.txt           # Python依赖
├── README.md                  # 项目文档
│
├── mingli_mcp/                # 可安装的Python包（唯一顶层命名空间）
│   ├── __init__.py           # 包版本
│   ├── cli.py                # 命令行入口（mingli-mcp / python -m mingli_mcp）
│   ├── config.py             # 配置管理
│   │
│   ├── mcp_server/           # MCP协议实现
│   │   ├── server.py         # 请求路由
│   │   ├── protocol.py       # initialize/prompts/resources、协议版本协商
│   │   ├── resources.py      # 资源内容
│   │   └── tools/            # 工具定义与handler
│   │
│   ├── core/                 # 核心抽象层
│   │   ├── base_system.py    # 命理系统抽象基类
│   │   ├── birth_info.py     # 生辰信息数据模型
│   │   └── chart_result.py   # 排盘结果数据模型
│   │
│   ├── transports/           # 传输层
│   │   ├── stdio_transport.py  # stdio传输（默认）
│   │   └── http_transport.py   # Streamable HTTP传输（无状态JSON模式）
│   │
│   ├── systems/              # 命理系统实现
│   │   ├── ziwei/            # 紫微斗数（已实现）
│   │   ├── bazi/             # 八字（已实现）
│   │   └── astrology/        # 占星（预留）
│   │
│   ├── utils/                # 工具函数（校验、格式化、限流等）
│   └── prompts/              # 提示词模板（随包发布）
│
├── cloudflare/                # Cloudflare Containers worker
├── wrangler.jsonc             # Cloudflare部署配置
├── docs/                      # 文档
├── examples/                  # 示例配置
├── scripts/                   # 脚本工具
└── tests/                     # 单元测试

🚀 扩展新命理系统

本项目采用插件化架构，添加新命理系统只需3步：

步骤1: 创建系统类

在 systems/ 下创建新目录，实现 BaseFortuneSystem 接口：

# systems/bazi/bazi_system.py
from core.base_system import BaseFortuneSystem

class BaziSystem(BaseFortuneSystem):
    def get_system_name(self) -> str:
        return "八字"
    
    def get_chart(self, birth_info):
        # 实现八字排盘逻辑
        return {...}
    
    # 实现其他必需方法...

步骤2: 注册系统

在 systems/__init__.py 中注册：

from .bazi import BaziSystem
register_system('bazi', BaziSystem)

步骤3: 添加MCP工具

在 mingli_mcp/mcp_server/tools/definitions.py 中添加工具定义，并在 tools/__init__.py 注册handler。

就这么简单！无需修改核心框架代码。

🔧 传输层扩展

当前默认使用 stdio 传输（适用于 Cursor）。未来可扩展：

HTTP传输（预留）

# transports/http_transport.py
class HttpTransport(BaseTransport):
    def __init__(self, host, port):
        # 实现HTTP服务器
        pass

WebSocket传输（预留）

# transports/ws_transport.py
class WebSocketTransport(BaseTransport):
    def __init__(self, host, port):
        # 实现WebSocket服务器
        pass

💡 最佳实践

在 AI 助手中使用

与AI助手（如Claude、Cursor等）对话时，可以直接使用自然语言查询：

紫微斗数示例：

• "帮我排一个紫微斗数盘：1990年5月20日，午时，男性"

• "查询这个人今年的运势如何"

• "分析他的财帛宫"

• "看看他适合什么行业"

八字示例：

• "帮我算八字：1985年3月15日，卯时，女性"

• "分析一下她的五行缺什么"

• "看看她今年所处的十年年龄段和流年干支"

• "什么五行的颜色适合她"

农历支持：

• "排盘：农历1995年7月初七，酉时，女性"

• "注意指定是农历"

提示词技巧

详细查询：

请帮我详细分析：
- 出生日期：2000年8月16日
- 出生时辰：寅时（早上5点）
- 性别：女
- 使用紫微斗数系统
- 重点看事业宫和财帛宫

对比分析：

请对比两个人的八字：
人A：1990年5月20日，午时，男
人B：1992年3月15日，辰时，女
看看他们的五行是否相配

运势追踪：

请记住这个人的信息：1988年10月1日，未时，男性
然后每个月帮我分析当月运势

📚 使用示例

在 Cursor 中使用

直接在对话中提问：

1. 获取紫微排盘:

帮我排一个紫微斗数盘：2000年8月16日，寅时，女性

2. 查询运势:

查询2000年8月16日寅时出生的女性，今天的紫微运势

3. 分析宫位:

分析上面这个人的命宫

4. 八字五行分析:

帮我看看这个人的五行：1995年7月10日，申时，男性

编程调用

from systems import get_system

# 获取紫微系统
ziwei = get_system('ziwei')

# 准备生辰信息
birth_info = {
    'date': '2000-08-16',
    'time_index': 2,  # 寅时
    'gender': '女',
    'calendar': 'solar'
}

# 获取排盘
chart = ziwei.get_chart(birth_info)
print(chart)

# 获取运势
from datetime import datetime
fortune = ziwei.get_fortune(birth_info, datetime.now())
print(fortune)

# 分析宫位
palace = ziwei.analyze_palace(birth_info, '命宫')
print(palace)

🧪 测试

# 运行测试（待实现）
pytest tests/

# 测试单个系统
python -m systems.ziwei.ziwei_system

⚙️ 配置说明

本服务采用零配置设计，所有配置都是可选的，服务器无需任何配置即可直接运行。

可用环境变量

如果需要自定义行为，可通过以下环境变量进行配置：

配置方法

方法1: 在MCP配置中设置

{
  "mcpServers": {
    "mingli": {
      "command": "uvx",
      "args": ["mingli-mcp"],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "DEFAULT_LANGUAGE": "zh-TW"
      }
    }
  }
}

方法2: 使用 .env 文件

# 创建 .env 文件
cat > .env << EOF
LOG_LEVEL=INFO
DEFAULT_LANGUAGE=zh-CN
TRANSPORT_TYPE=stdio
EOF

方法3: 系统环境变量

export LOG_LEVEL=DEBUG
export DEFAULT_LANGUAGE=zh-CN
python -m mingli_mcp

Apify 托管与计费

Apify Actor 以 Standby 模式对外提供 POST /mcp。在 Console 中使用 Pay-per-event 定价时，事件名必须配置为 tool-call。

• 只有成功的 MCP tools/call 请求会产生一次计费事件。

• tools/list 等发现请求以及执行失败的工具请求不计费。

• 平台未能确认计费时，服务不会返回工具结果：额度已用尽或无法计费返回 MCP 错误 -32001，计费 API 异常返回 -32603。

• Apify 入口未安装 SDK 时会直接启动失败，避免意外绕过计费。本地开发请使用项目原有入口。

Cloudflare 和 Apify 的部署配置可以同时保留在公开仓库中。不要提交 .env、 API token 或其他密钥；Apify 账户配置和支付信息应仅保存在平台 Console 中。

📝 依赖说明

• iztro-py: 紫微斗数核心库（纯 Python 实现，性能比 py-iztro 提升 10 倍）

• python-dotenv: 环境变量管理

• python-dateutil: 日期处理

🗺️ 未来规划

• 完善八字系统实现

• 添加西方占星系统

• 实现合盘功能

• HTTP/WebSocket传输层

• 命理知识库集成

• AI解读功能

• 更多运势分析维度

🤝 贡献

欢迎贡献代码、报告问题或提出建议！

📄 许可证

MIT License

🙏 致谢

• iztro - 紫微斗数 JavaScript 库（原始算法来源）

• iztro-py - 紫微斗数纯 Python 实现

• MCP Protocol - Model Context Protocol 规范

🔮 开始你的命理探索之旅！