bazi-reader-mcp – 开源八字MCP服务器

bazi-reader-mcp 是一个开源的八字（四柱推命/사주팔자）计算引擎与 MCP（Model Context Protocol）服务器，旨在让 AI 代理（如 Claude、Cursor、Cline 等）能够直接读取并分析中国传统八字命盘。

该项目由顺时（Shunshi.AI）团队开源，底层使用纯 TypeScript 编写的 shunshi-bazi-core 库，并封装为 shunshi-bazi-mcp MCP 服务包，解决了现有开源八字库中普遍存在的真太阳时缺失、子时处理不一致、缺乏校验基准以及多语言支持不足四大痛点。无论是开发者想要在自己的应用中嵌入八字计算，还是希望让 AI 助手具备八字排盘能力，这个项目都提供了现成、计算准确的解决方案。

网址： https://github.com/shunshi-ai/bazi-reader-mcp/

在线版本：https://123one.top/bazi-reader

核心功能

该项目由两个发布的 npm 包组成，各司其职：

• shunshi-bazi-core：纯 TypeScript 计算库，零框架依赖，可在 Node.js 或浏览器中直接使用。核心能力包括：
• 根据出生年月日、出生时刻、出生地（城市或经纬度）计算四柱（年柱、月柱、日柱、时柱）。
• 自动进行真太阳时（均时差）校正，默认开启，解决了远离时区标准经线地区（如新疆、黑龙江、美国西海岸、北海道）因时钟时间直接使用导致的时柱错误问题。
• 默认采用 子时 sect=1 规则（23:00 归入次日日柱），与国内专业参考工具“问真八字”一致。
• 输出十神、大运、五行平衡等完整命盘信息。
• 支持多语言关键词检索（bazi / 八字 / 四柱推命 / 사주팔자 / saju / shichu-suimei），方便日、韩、英开发者发现和使用。
• shunshi-bazi-mcp：轻量 MCP 协议服务器，封装核心库，作为 Claude Desktop、Cursor、Cline 等 MCP 客户端的即插即用工具。安装后 AI 代理可像调用函数一样直接获取八字排盘结果。

两个包共享同一计算引擎，每次发布均经过5 条黄金案例与 Shunshi.AI Python 后端的 5/5 完全一致校验，以及 cantian-tymext 库的 刑冲合会 子集 5/5 校验，保证计算准确性。

使用体验

对于开发者而言，使用体验非常顺畅：

• 快速安装：通过 npm 即可安装。在项目中运行 npm install shunshi-bazi-core 即可引入核心计算函数，调用 getBaziChart() 传入出生日期、时间、地点即可获得 JSON 格式的完整命盘。若要让 AI 代理直接使用，只需运行 npx -y shunshi-bazi-mcp 启动 MCP 服务器，并在 AI 客户端中配置该服务器端点。
• 零配置默认值：真太阳时默认开启，子时规则默认采用一致策略，开发者无需手动调整参数就能得到与专业工具一致的结果，大幅降低了使用门槛。
• 多语言友好：代码注释和文档关键词覆盖中、日、韩、英四种语言，即使不熟悉中文的日韩开发者也能轻松理解。AI 代理输出的结果字段采用中文术语，但项目本身对多语言上下文有良好适配。
• 与 AI 代理无缝集成：通过 MCP 协议，AI 可以自主调用排盘工具，无需人工输入，适合在对话中实时生成八字分析报告。

价格方案

该项目为 完全开源免费 的项目，采用 MIT 许可证（仓库中包含 LICENSE 文件）。两个 npm 包均以 MIT 许可发布，开发者可以自由使用、修改、再分发，无需支付任何费用。无论是个人学习、商业集成还是二次开发，都没有授权或订阅成本。Shunshi.AI 团队将生产环境中的计算引擎开源出来，降低了八字命理技术研究的门槛。

适用场景

该 MCP 服务器适合以下场景：

• AI 助手集成：让 Claude、Cursor 等智能代理具备八字排盘能力，在对话中直接分析用户的生辰五行、十神格局、大运流年。
• 八字命理学习与研究：开发者或命理爱好者可将其作为准确的计算基准，用于验证其他工具或算法。
• 多语言应用开发：面向日本（四柱推命）或韩国（사주팔자）用户的应用，直接调用该库避免重复造轮子。
• 在线排盘工具构建：通过 core 库快速搭建 Web 八字计算页面，或通过 MCP 服务与前端后端解耦。
• 真太阳时校正需求：需要处理非标准时区出生时间的专业排盘系统，该项目内置了精确的天文时间修正。

综合评价，优缺点

优点：

1. 真太阳时内置且默认启用：这是开源八字库中极为罕见的特性，直接解决了因时区偏差导致的排列错误，尤其对高纬度或远离标准经线的出生地至关重要。
2. 子时规则明确且一致：采用问真八字相同的 sect=1 规则（23:00 为次日），避免了不同库之间的分歧，使结果可与其他专业工具互相印证。
3. 经过严格校验：与 Shunshi.AI 生产后端及第三方命题库进行 5/5 全量校验，计算可靠性高，可作为基准参考。
4. 多语言支持：关键词和文档覆盖中、日、韩、英，降低了跨语言开发者使用门槛，利于国际化传播。
5. 开箱即用的 MCP 服务：一行命令即可让 AI 代理接入，无需编写额外集成代码。

缺点：

1. 无图形界面：目前仅提供 API 和 MCP 服务，没有 Web UI 或客户端界面，对非开发者用户不友好，需自行搭建界面或依赖 AI 客户端展示。
2. 依赖 MCP 客户端：MCP 服务器模式需要客户端支持 MCP 协议（如 Claude Desktop、Cursor），如果使用其他 AI 工具可能无法直接调用。
3. 文档和示例相对精简：虽然核心功能强大，但 README 中的使用示例有限，复杂场景（如自定义大运起运规则、特殊格局判断）可能需参考代码自行探索。
4. 默认策略固定：子时规则和真太阳时默认开启无法通过简单参数关闭（需要修改源码或传递额外参数），对于想要使用传统时钟时间的用户来说不够灵活。

总体而言，这是一个专业、准确、易集成的八字计算开源项目，尤其适合 AI 时代需要让智能体具备传统文化知识能力的开发者。如果你正在寻找一个靠谱的八字排盘引擎，它值得一试。