🔌 MCP Servers
Ziwei & Bazi Astrology
Generate Ziwei Doushu and Bazi charts with insights into palaces, stars, and the five elements. Explore fortunes across decades, years, months, days, and hours to time decisions and plan ahead. Compar
Description
命理MCP服务 (Mingli MCP Server)
一个支持多种命理系统（紫微斗数、八字、占星等）的 Model Context Protocol (MCP) 服务器，专为 AI 工具（如 Cursor IDE）设计。
✨ 特性
🎯 核心特性
- ✅ 多命理系统支持: 采用插件化架构，轻松扩展新的命理系统
- ✅ 紫微斗数（已实现）
- ✅ 八字（已实现）⭐ 新增
- 🔄 西方占星（预留接口）
- ✅ 多语言支持: 支持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两种输出格式
- ⭐ 真太阳时: 支持全球200+城市的精确时辰修正 新功能
🎴 八字功能 ⭐ 新增
- ✅ 四柱排盘: 年月日时四柱、天干地支详细信息
- ✅ 十神分析: 比肩、劫财、食神、伤官、偏财、正财、七杀、正官、偏印、正印
- ✅ 五行分析: 金木水火土分数、百分比、平衡度
- ✅ 地支藏干: 详细的地支藏干信息
- ✅ 运势查询: 大运、流年分析
- ✅ 缺失分析: 自动识别五行缺失并给出建议
- ✅ 多种历法: 支持阳历和农历输入
- ⭐ 真太阳时: 支持全球200+城市的精确时辰修正 新功能
📚 文档导航
新用户推荐阅读路径：
-
快速开始指南 ⭐ - 5分钟快速上手
- 安装方法（uvx、pip、Docker）
- IDE配置示例
- 第一次排盘体验
-
用户指南 - 完整功能说明
- 所有工具详解
- 参数说明
- 输出格式对比
- 使用限制
-
真太阳时使用指南 ⭐ - 精确时辰修正（新功能）
- 200+全球城市支持
- 自动时辰修正
- 适用于西北地区
-
API使用示例 - 17个实用代码示例
- 基础用法
- 紫微斗数、八字示例
- 高级模式（批量处理、错误处理）
-
故障排查指南 - 16个常见问题解决方案
- 安装问题
- 配置问题
- 运行时错误
- 调试技巧
开发者文档：
📋 可用工具
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, 可选): 是否闰月，默认 falseformat(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-DDtime_index(integer, 必需): 时辰序号 0-12gender(string, 必需): 性别 "男" 或 "女"calendar(string, 可选): 历法 "solar"(阳历) 或 "lunar"(农历), 默认 "solar"is_leap_month(boolean, 可选): 是否闰月，默认 falseformat(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, 可选): 输出格式
输出包含:
- 日主及其五行属性
- 五行分数和百分比
- 最旺/最弱五行
- 缺失五行
- 平衡度评价
- 补救建议
🚀 快速开始
在线体验
- 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. 测试运行
chmod +x mingli_mcp.py
python mingli_mcp.py
6. 配置 Cursor MCP
编辑或创建 ~/.cursor/mcp.json:
{
"mcpServers": {
"mingli": {
"command": "/Users/lix18854/Documents/code/ziwei_mcp/venv/bin/python",
"args": ["/Users/lix18854/Documents/code/ziwei_mcp/mingli_mcp.py"],
"env": {
"LOG_LEVEL": "INFO"
}
}
}
}
注意: 请根据实际路径调整
command和args
7. 重启 Cursor
重启 Cursor IDE 以加载新的 MCP 配置。
📁 项目结构
ziwei_mcp/
├── mingli_mcp.py # MCP服务器主入口
├── config.py # 配置管理
├── requirements.txt # Python依赖
├── pyproject.toml # 项目配置
├── .gitignore # Git忽略文件
├── README.md # 项目文档
│
├── core/ # 核心抽象层
│ ├── __init__.py
│ ├── base_system.py # 命理系统抽象基类
│ ├── birth_info.py # 生辰信息数据模型
│ └── chart_result.py # 排盘结果数据模型
│
├── transports/ # 传输层（支持多种传输方式）
│ ├── __init__.py
│ ├── base_transport.py # 传输层抽象基类
│ └── stdio_transport.py # stdio传输实现（默认）
│
├── systems/ # 命理系统实现
│ ├── __init__.py # 系统注册中心
│ ├── ziwei/ # 紫微斗数（已实现）
│ │ ├── __init__.py
│ │ ├── ziwei_system.py # 系统实现
│ │ └── formatter.py # 结果格式化
│ ├── bazi/ # 八字（已实现）
│ │ ├── __init__.py
│ │ ├── bazi_system.py # 系统实现
│ │ └── formatter.py # 结果格式化
│ └── astrology/ # 占星（预留）
│ └── __init__.py
│
├── utils/ # 工具函数
│ ├── __init__.py
│ ├── validators.py # 参数验证
│ └── formatters.py # 响应格式化
│
├── docs/ # 文档
│ ├── README.md # 文档索引
│ ├── guides/ # 用户指南
│ ├── deployment/ # 部署文档
│ ├── architecture/ # 架构设计
│ └── development/ # 开发文档
│
├── examples/ # 示例配置
│ └── config/ # 配置文件示例
│ ├── .env.example
│ ├── codex_config.toml.example
│ └── cursor_mcp_config.example.json
│
├── scripts/ # 脚本工具
│ ├── tests/ # 测试脚本
│ └── check_ready_to_publish.sh
│
└── tests/ # 单元测试
└── __init__.py
🚀 扩展新命理系统
本项目采用插件化架构，添加新命理系统只需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.py 的 _handle_tools_list() 中添加工具定义。
就这么简单！无需修改核心框架代码。
🔧 传输层扩展
当前默认使用 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 中使用
直接在对话中提问：
- 获取紫微排盘:
帮我排一个紫微斗数盘：2000年8月16日，寅时，女性
- 查询运势:
查询2000年8月16日寅时出生的女性，今天的紫微运势
- 分析宫位:
分析上面这个人的命宫
- 八字五行分析:
帮我看看这个人的五行：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
⚙️ 配置说明
本服务采用零配置设计，所有配置都是可选的，服务器无需任何配置即可直接运行。
可用环境变量
如果需要自定义行为，可通过以下环境变量进行配置：
| 环境变量 | 描述 | 默认值 | 示例 |
|---|---|---|---|
LOG_LEVEL |
日志级别 | INFO |
DEBUG, INFO, WARNING, ERROR |
TRANSPORT_TYPE |
传输协议类型 | stdio |
stdio, http |
HTTP_HOST |
HTTP监听地址（仅http模式） | 0.0.0.0 |
127.0.0.1, 0.0.0.0 |
HTTP_PORT |
HTTP监听端口（仅http模式） | 8080 |
8080, 3000 |
HTTP_API_KEY |
HTTP API密钥（可选） | "" |
your-secret-key |
DEFAULT_LANGUAGE |
默认输出语言 | zh-CN |
zh-CN, zh-TW, en-US, ja-JP, ko-KR, vi-VN |
配置方法
方法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 mingli_mcp.py
📝 依赖说明
- 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 规范
🔮 开始你的命理探索之旅！
Reviews (0)
Sign in to write a review.
No reviews yet. Be the first to review!
Comments (0)
No comments yet. Be the first to share your thoughts!