内容
# 命盘 MCP Server
**简体中文（主文档）** | [English](README.en.md) | [日本語](README.ja.md)
[](https://github.com/ChesterRa/mingpan)
[](LICENSE)
**命盘（Mingpan）** 是一个开源的中华传统术数 MCP 计算引擎，为 AI 应用提供命理排盘与占卜起卦能力。BaziWei 同时维护可直接使用的官方远程服务。
## 立即使用官方 MCP
将下面的端点添加到支持 Remote MCP / Streamable HTTP 的 AI 客户端：
```text
https://mingpan.bzwai.com/mcp
```
无需安装 Node.js，也无需自行部署服务器。添加后可以直接尝试：
> 请帮我排一个八字命盘，1992年4月12日7点30分，男性
> 请帮我起一个奇门遁甲时盘，2024年6月21日10点
先访问 [Mingpan 开源项目网站](https://mingpan.bzwai.com) 可查看能力范围与连接说明。官方服务由 [BaziWei](https://bzwai.com) 维护；源代码与计算口径继续在本仓库公开，方便审阅、复现与共同改进。
## 特性
- **MCP 原生**：无缝集成 Claude Desktop 及 Claude Code
- 🌏 **中文输出**：以简体为主，术语保持传统
- 📊 **结构化文本**：便于 AI 理解与分析的格式
- 🕐 **多时区支持**：海外出生/起卦时间自动换算为北京时间排盘
## 使用方式
| 形态 | 适用 | 用法 |
| ---- | ---- | ---- |
| **官方远程 MCP**（推荐） | 支持 Remote MCP / Streamable HTTP 的 AI 客户端 | 添加 `https://mingpan.bzwai.com/mcp` |
| **本地 stdio MCP** | 本地开发、离线使用或要求资料不离开设备 | 见下方可选配置 |
官方远程服务使用无状态纯计算：不建立命盘数据库，不缓存或记录出生参数与命盘结果。若要求资料完全不离开设备，可选择本地 stdio 形态。
## 本地运行（可选）
### Claude Desktop
找到配置文件并添加以下内容：
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"mingpan": {
"command": "npx",
"args": ["-y", "mingpan"]
}
}
}
```
### Claude Code
```bash
claude mcp add mingpan -- npx -y mingpan
```
### 验证
配置完成后重启客户端，然后尝试：
> 请帮我排一个八字命盘，1992年4月12日7点30分，男性
> 请帮我起一个奇门遁甲时盘，2024年6月21日10点
## 工具列表
### 命理排盘
命理学基于出生时间推算人生运势，属于「命」的范畴。
#### 八字命理
| 工具 | 说明 |
| -------------- | ------------------------------------------ |
| `bazi_basic` | 八字四柱排盘（干支纳音、天干/藏干十神、十二长生自坐、命宫/胎元、旬空、公农历对照；五行/格局/用神由 AI 分析） |
| `bazi_dayun` | 大运列表（十年一运） |
| `bazi_liunian` | 流年列表（指定年份范围） |
| `bazi_liuyue` | 流月列表（节气月，立春起算） |
| `bazi_liuri` | 流日列表（指定月份内每日） |
#### 紫微斗数
| 工具 | 说明 |
| ---------------- | ---------------------------------------- |
| `ziwei_basic` | 紫微命盘排盘（十二宫、主星、辅星、五行局/命主/身主、四化） |
| `ziwei_daxian` | 大限列表（十年一限） |
| `ziwei_xiaoxian` | 小限列表（每年一宫） |
| `ziwei_liunian` | 流年列表（指定年份范围） |
| `ziwei_liuyue` | 流月列表（农历月） |
| `ziwei_liuri` | 流日列表（农历日） |
### 历法原语
历法计算是所有术数的公共地基，也可独立使用。
| 工具 | 说明 |
| ---------------- | ---------------------------------------------- |
| `jieqi_query` | 二十四节气精确时刻查询（精确到秒，北京时间） |
| `calendar_convert` | 公历/农历互转（含闰月、干支年月日、生肖） |
节气是天文事件（AI 无法推算，如 2025 年立春是 2 月 3 日 22:10 而非 2 月 4 日），
农历闰月分配无简单规律（AI 经常猜错）——两者是本产品确定性计算的核心价值。
### 占卜起卦
占卜术基于起卦时间或随机数推演卦象，属于「卜」的范畴。
#### 六爻
| 工具 | 说明 |
| -------------- | --------------------------------------------------- |
| `liuyao_basic` | 六爻排盘（本卦/变卦、纳甲、六亲、六神、世应、旬空、伏神/飞神、进退神、旺衰） |
六爻输入为六个爻值（自下而上）：
- 6 = 老阴（动爻，阴变阳）
- 7 = 少阳（静爻）
- 8 = 少阴（静爻）
- 9 = 老阳（动爻，阳变阴）
#### 梅花易数
| 工具 | 说明 |
| -------------- | ---------------------------------------- |
| `meihua_basic` | 梅花易数排盘（本卦/变卦/互卦、体用分析） |
支持两种起卦方式：
- 时间起卦：根据农历年月日时计算
- 数字起卦：根据两个数字计算
爻位统一**自下而上**编号 1–6；变卦反转指定动爻，互卦取本卦第 2、3、4 爻为下卦，第 3、4、5 爻为上卦。依据为《梅花易数》卷一的[八卦象例、爻以六除与互卦起例](https://zh.wikisource.org/wiki/梅花易數/卷一)。当前实现对乾、坤也按相同爻位取互；未采用原文另述的“乾坤无互，互其变卦”分支。
**0.1.8 修复**：[Issue #2](https://github.com/ChesterRa/mingpan/issues/2) 指出的爻序映射错误会影响旧版的变卦和互卦。按上述取互规则，64 卦 × 6 动爻中有 256 个变卦结果、64 卦中有 60 个互卦结果需要纠正。时间与数字起卦均受影响；本卦、动爻编号与本卦体用关系不变，输入参数和文本结构兼容。升级后，依赖旧互变卦的解读需重新计算后复核。
#### 大六壬
| 工具 | 说明 |
| ---------------- | -------------------------------------------------- |
| `daliuren_basic` | 大六壬排盘（天地盘、四课、三传、十二天将、神煞） |
大六壬为三式之首。**推荐直接输入公历起课时间**（year/month/day/hour），
节气、月将、日干支、时干支由系统自动推得（LLM 手推干支极易出错）。
也可显式指定 `jieqi`/`dayGanZhi`/`hourGanZhi`（专家模式，向后兼容）。
#### 奇门遁甲
| 工具 | 说明 |
| --------------- | ---- |
| `qimen_basic` | 奇门遁甲排盘（九宫布局、三奇六仪、八门九星八神、格局检测） |
| `qimen_yongshen`| 奇门用神分析（按事类选取用神，含主客、旺衰、空亡、入墓等确定性信息） |
奇门遁甲为三式之一，盘式与规则主要参考张志春《神奇之门》，支持：时盘/日盘/月盘/年盘、转盘/飞盘、拆补法/茅山法。
## 输出示例（bazi_basic）
```text
=== 命主資料 ===
性別：男
公曆：1992-04-12 07:30:00
農曆：壬申年三月初十辰時
=== 八字命盤 ===
年柱：壬申（剑锋金） 月柱：甲辰（覆灯火） 日柱：戊午（天上火） 時柱：丙辰（沙中土）
日柱旬空：子丑
命宮：己酉 胎元：乙未
天干十神：年干水=偏財 月干木=七殺 時干火=偏印
藏干十神（※本氣）：年申[庚食神※ 壬偏財 戊比肩] 月辰[戊比肩※ 乙正官 癸正財] 日午[丁正印※ 己劫財] 時辰[戊比肩※ 乙正官 癸正財]
十二長生（自坐）：年长生 月衰 日帝旺 時冠带
```
只包含确定性排盘信息；五行强弱、格局、用神等解读由 AI 依据盘面自行分析。
## 输入参数
### 命理工具（八字/紫微）
| 参数 | 类型 | 必填 | 说明 |
| --------- | ------- | ---- | ---------------------------- |
| year | number | ✓ | 出生年份（1900-2100） |
| month | number | ✓ | 出生月份（1-12） |
| day | number | ✓ | 出生日期（1-31） |
| hour | number | ✓ | 出生时辰（0-23） |
| minute | number | | 出生分钟（0-59），默认 0 |
| gender | string | ✓ | `male` / `female` |
| longitude | number | | 出生地经度，用于真太阳时校正 |
| isLunar | boolean | | 是否为农历输入，默认 false |
| timezone | string | | IANA 时区名（如 `America/New_York`），默认北京时间 |
### 时区说明（v0.1.4+）
- 输入时间默认按**北京时间**排盘
- 海外出生/起卦时提供 `timezone` 参数，系统将当地墙钟时间换算为北京时间后计算
- 输入侧使用 IANA 时区数据库（正确处理各国历史夏令时，如 1986-1991 年中国夏令时）
- 内部规范表示为 UTC+8 平太阳时，与历法换算口径一致
### 占卜工具（六爻/梅花/大六壬）
- 六爻/梅花：输入起卦时间（支持 `timezone`），爻值/卦数由调用方提供
- 大六壬：**推荐直接输入公历时间**，节气与干支自动推得；也可显式指定（专家模式）
### 奇门遁甲工具
| 参数 | 类型 | 必填 | 说明 |
| ------------ | ------- | ---- | ---- |
| year | number | ✓ | 起盘年份（1900-2100） |
| month | number | ✓ | 起盘月份（1-12） |
| day | number | ✓ | 起盘日期（1-31） |
| hour | number | ✓ | 起盘时辰（0-23） |
| minute | number | | 分钟（0-59），默认 0 |
| isLunar | boolean | | 是否为农历输入，默认 false |
| timezone | string | | IANA 时区名，默认北京时间 |
| panType | string | | `时盘` / `日盘` / `月盘` / `年盘`，默认 `时盘` |
| panStyle | string | | `转盘` / `飞盘`，默认 `转盘` |
| zhiRunMethod | string | | `chaibu`（拆补法）/ `maoshan`（茅山法），默认 `chaibu` |
## 月份基准说明
| 系统 | 月份基准 | 日期基准 |
| ---- | ------------------ | -------- |
| 八字 | 节气月（立春起算） | 公历日 |
| 紫微 | 农历月（初一起算） | 农历日 |
## 开发
```bash
git clone https://github.com/ChesterRa/mingpan.git
cd mingpan
npm ci
npm run check # 构建 + 完整测试
npm run deploy:worker:dry-run # 只验证 Worker 打包，不部署
npm run dev # 监听变化
```
## 依赖
| 库 | 用途 |
| --------------------------- | ---------------- |
| `@modelcontextprotocol/server` | MCP v2 服务端协议实现 |
| `@modelcontextprotocol/client` | MCP v2 协议集成测试 |
| `lunar-javascript` | 农历/公历转换 |
| `iztro` | 紫微斗数计算引擎 |
| `zod` | 输入参数校验 |
## 路线图
- [x] 八字基础排盘与时运列表
- [x] 紫微基础排盘与时运列表
- [x] 六爻排盘
- [x] 梅花易数排盘
- [x] 大六壬排盘
- [x] 奇门遁甲排盘
- [x] 大六壬时间起课（自动推节气/干支）
- [x] 多时区支持（timezone 参数）
- [x] 奇门口径修正（拆补符头、地盘布局、转盘星门，参照《神奇之门》与 kinqimen 交叉验证）
- [x] 排盘完整性对称盘点（八字补纳音/藏干十神/十二长生/命宫胎元，紫微补五行局/命主/身主）
- [x] 输出契约测试全覆盖 + 权威用例金样本（历史人物记载、立春分钟级边界、iztro 适配保真）
## 版本历史
| 版本 | 说明 |
| ---- | ---- |
| [0.1.8](docs/release-notes-0.1.8.md) | **梅花正确性修复**：统一八卦爻序与反向映射，纠正变卦和互卦；独立位运算穷举 384 种变卦与 64 种互卦，补齐 MCP、HTTP 与构建后 stdio 回归；感谢 [@1270643866](https://github.com/1270643866) 的详细报告 |
| 0.1.7 | **官方托管服务**：`mingpan.bzwai.com` 产品站与 `/mcp` 同仓、同版本、同一 Worker 发布；生产域名、无状态隐私边界、Host/Origin、请求体、限流与现代 MCP 协议烟雾测试完成收口；测试 300 |
| 0.1.6 | **MCP SDK v2 迁移**（2026-07-28 无状态协议，原生支持 Cloudflare Workers，向后兼容旧客户端）；远程 HTTP 入口从 50 行简化为 20 行（createMcpHandler）；Workers 打包 gzip 638→606KB；测试 288 |
| 0.1.5 | **口径裁决**：子初换日（23:00 起日柱时柱同属次日，全五系统统一）；起运权威化（lunar 节气表 + 交运日历定位）；奇门年盘按《遁甲演义》典籍修正；真太阳时四柱全量生效；**新能力**：历法原语层（jieqi_query + calendar_convert）；测试 218→288 |
| 0.1.4 | **正确性修复**：八字立春换年、奇门四类口径修正、stdio 日志修复；**输出定位确立**：只输出确定性排盘量；大六壬时间起课、多时区；测试 117→218 |
| 0.1.3 | 奇门用神分析与择日 |
| 0.1.2 | 六爻、梅花易数、大六壬 |
| 0.1.0 | 首个发布：八字、紫微 |
## 许可证
Apache License 2.0
连接信息
猜你喜欢
暂无推荐服务器