saju-mcp

Saju MCP — 韩国四柱与 BaZi 占星术

一个 MCP（Model Context Protocol）服务，封装了 Saju API —— 韩国四柱命理（사주팔자 / BaZi / 八字），让任何支持 MCP 的 AI 客户端（Claude Desktop、Cursor、VS Code、Windsurf 和自定义 Agent）都能在对话中直接计算、解读和比较韩国 Saju 命盘。

SAJU_API_KEY="sajuapi_free_xxx" npx saju-mcp

30 秒上手：获取免费密钥 → 添加配置 → 向 AI 客户端提问 “计算一位 1990-05-15 14:00 出生的男性的 Saju。”

为什么选择这个 MCP？

• 唯一可作为 MCP 服务使用的生产级韩国 Saju 引擎。
• 经 KASI 验证的农历转换（交叉核对超过 47,000 天，零失败）。
• 十神（十神）+ 用神（用神）+ 大运（大運）——通用西方占星 API 不具备的解读功能；这类 API 只会返回太阳/月亮星座。
• 支持 10 种输出语言：韩语、英语、日语、中文、西班牙语、葡萄牙语、越南语、印度尼西亚语、印地语、泰语。
• **免费套餐：每天 100 次请求，无需信用卡。**采用免费增值模式——今天即可开始构建，仅在应用需要生产级用量时升级。

由线上 API https://saju-api.pages.dev 提供支持。

实际使用效果

用自然语言向 AI 客户端提问；它会调用 saju_calculate 并获取可供推理的结构化数据。以下是线上 API 对 { year: 1990, month: 5, day: 15, hour: 14, gender: "M", lang: "en" } 返回的真实、未经编辑的响应：

{
  "pillars": {
    "year":  { "stem": "경", "branch": "오", "stem_hanja": "庚", "branch_hanja": "午" },
    "month": { "stem": "신", "branch": "사", "stem_hanja": "辛", "branch_hanja": "巳" },
    "day":   { "stem": "경", "branch": "진", "stem_hanja": "庚", "branch_hanja": "辰" },
    "hour":  { "stem": "계", "branch": "미", "stem_hanja": "癸", "branch_hanja": "未" }
  },
  "elements": { "wood": 0, "fire": 2, "earth": 2, "metal": 3, "water": 1 },
  "day_master": { "stem": "경", "element": "metal", "polarity": "yang" },
  "zodiac": "horse",
  "tier": "free",
  "remaining": 99
}

每个响应都会同时以人类可读文本和 structuredContent 的形式返回给模型，因此 Agent 可以直接根据 day_master.element、elements、合婚 score 等字段进行分支处理，无需重新解析文字。

工具

快速开始

1. 获取免费 API 密钥（无需信用卡）

免费套餐每天可请求 100 次，无需信用卡：

curl -X POST https://saju-api.pages.dev/api/v1/keys/create \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

响应中包含一个格式为 sajuapi_free_... 的 api_key：

{
  "api_key": "sajuapi_free_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "tier": "free",
  "daily_limit": 100,
  "rps": 1,
  "monthly_price_usd": 0,
  "note": "Store this key safely — it is shown only once. Send with header `X-API-Key: <key>`."
}

密钥仅显示一次——请立即保存。密钥通过 SAJU_API_KEY 环境变量传递给服务，绝不会硬编码。（不接受一次性邮箱或 example.com 邮箱域名——请使用真实邮箱地址。）

2.（可选）无需 MCP 客户端即可进行冒烟测试

npx 可直接从 npm 运行服务，无需克隆仓库或本地构建：

SAJU_API_KEY="sajuapi_free_xxx" npx -y saju-mcp

服务通过标准输入/输出（stdio）使用 MCP，并提供四个 saju_* 工具。按 Ctrl-C 退出。

3. 在 MCP 客户端中注册

该服务基于 stdio，因此每个 MCP 客户端都使用相同的三项配置： command: npx、args: ["-y", "saju-mcp"]，以及包含 SAJU_API_KEY 的 env。

{
  "mcpServers": {
    "saju": {
      "command": "npx",
      "args": ["-y", "saju-mcp"],
      "env": { "SAJU_API_KEY": "sajuapi_free_your_key_here" }
    }
  }
}

{
  "mcpServers": {
    "saju": {
      "command": "npx",
      "args": ["-y", "saju-mcp"],
      "env": { "SAJU_API_KEY": "sajuapi_free_your_key_here" }
    }
  }
}

{
  "servers": {
    "saju": {
      "command": "npx",
      "args": ["-y", "saju-mcp"],
      "env": { "SAJU_API_KEY": "sajuapi_free_your_key_here" }
    }
  }
}

{
  "mcpServers": {
    "saju": {
      "command": "npx",
      "args": ["-y", "saju-mcp"],
      "env": { "SAJU_API_KEY": "sajuapi_free_your_key_here" }
    }
  }
}

重启 / 重新加载客户端。四个 saju_* 工具会显示在工具列表中。

工具输入示例

saju_calculate / saju_interpret：

{ "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "M", "lang": "en" }

（如果出生时辰未知，则 hour: -1。）

saju_compatibility：

{
  "person_a": { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "M" },
  "person_b": { "year": 1992, "month": 8, "day": 3,  "hour": 9,  "gender": "F" },
  "lang": "en"
}

saju_daily（来自先前 calculate/interpret 调用的日主）：

{ "day_master": "갑", "date": "2026-06-17", "lang": "en" }

输入范围（由服务端验证，与 API 保持一致）：year 为 1920–2050， month 为 1–12，day 为 1–31，hour 为 -1–23，gender 为 "M"|"F"，lang 为 10 种 受支持代码之一（默认值为 ko）。

环境变量

错误与故障排除

上游调用失败时，工具会返回 MCP 错误结果（isError: true）， 其文本为 Saju API error <status>: <body>，后面附带提示。常见情况：

密钥不会出现在工具输出或日志中。如果密钥泄露，请创建一个新密钥——旧密钥仍有独立配额，可弃用。

从源代码开发 / 构建

git clone https://github.com/ghdejr11-beep/saju-mcp.git
cd saju-mcp
npm install
npm run build      # compiles src/index.ts -> dist/index.js
npm run typecheck  # tsc --noEmit

直接运行本地构建：

{
  "mcpServers": {
    "saju": {
      "command": "node",
      "args": ["/absolute/path/to/saju-mcp/dist/index.js"],
      "env": { "SAJU_API_KEY": "sajuapi_free_your_key_here" }
    }
  }
}

需要 Node.js 18+（使用内置的全局 fetch）。

升级到生产环境

免费版（每天 100 次请求，每秒 1 次请求）适用于开发和评估。应用 发布后，可在同一 API 上使用更高用量的套餐——请访问 https://saju-api.pages.dev 查看当前套餐和密钥接口。代码 和配置无需更改；只需更换密钥。

相关项目

• Korea Calendar API — 通过 REST 提供韩国公共假日、阴历↔阳历转换、干支（간지）柱 和 24 节气。需要获取 saju 解读背后的原始历法数据时，可与此服务自然搭配使用： https://korea-calendar-api.kunstudio.workers.dev

许可证

专有 — KunStudio。封装 Saju API；须遵守该 API 的条款。