saju-mcp

Saju MCP — 韓国の四柱推命とBaZi占星術

Saju API（Model Context Protocol）をラップするMCP（Model Context Protocol）サーバーです。韓国の四柱推命（사주팔자 / BaZi / 八字）を扱い、MCP 対応のAIクライアント（Claude Desktop、Cursor、VS Code、Windsurf、カスタムエージェントなど）が、会話中に韓国の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にはない解釈機能を備えています。
• 10言語で出力：韓国語、英語、日本語、中国語、スペイン語、ポルトガル語、ベトナム語、インドネシア語、ヒンディー語、タイ語。
• 無料枠：1日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の両方としてモデルに返されます。そのため、エージェントは文章を再解析することなく、day_master.element、elements、相性のscoreなどに基づいて処理を分岐できます。

ツール

クイックスタート

1. 無料のAPIキーを取得する（カード不要）

無料枠は1日100リクエスト、クレジットカード不要です。

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

レスポンスにはapi_keyが含まれ、形式はsajuapi_free_...です。

{
  "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を通信し、4つのsaju_*ツールを公開します。終了するにはCtrl-Cを押してください。

3. MCP クライアントに登録する

このサーバーは stdio ベースなので、どの MCP クライアントでも同じ 3 つの項目を使用します。 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" }
    }
  }
}

クライアントを再起動／再読み込みします。4 つの 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）：

{ "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）です。

環境変数

エラーとトラブルシューティング

上流への呼び出しに失敗すると、ツールはテキストが Saju API error <status>: <body> とヒントを含む MCP エラー結果（isError: true）を返します。よくあるケースは次のとおりです。

キーがツールの出力やログに表示されることはありません。キーが漏えいした場合は、新しいキーを発行してください。古いキーのクォータはそのまま維持され、使用を停止できます。

ソースから開発／ビルドする

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 を使用します）。

本番環境へのアップグレード

無料プラン（1 日あたり 100 req、1 rps）は開発と評価向けです。アプリを リリースする際は、同じ API でより大容量のプランを利用できます。現在のプランとキーのエンドポイントについては https://saju-api.pages.dev をご覧ください。コードと設定は変更不要で、キーのみ変更します。

関連情報

• Korea Calendar API — REST 経由で、韓国の祝日、太陰暦↔太陽暦の変換、 干支（간지）の柱、二十四節気を提供します。四柱推命の鑑定の基となる暦の情報が必要な場合に、 このサーバーと自然に連携できます： https://korea-calendar-api.kunstudio.workers.dev

ライセンス

プロプライエタリ — KunStudio。Saju API をラップしています。利用は同 API の規約に従います。