saju-mcp

Saju MCP Server

An MCP (Model Context Protocol) server that wraps the Saju API — Korean Four Pillars of Destiny (사주팔자 / Bazi) — so MCP-capable clients (Claude Desktop, Cursor, and other MCP hosts) can compute and interpret Saju directly in a conversation.

Backed by the live API at https://saju-api.pages.dev (10 languages: ko, en, ja, zh, es, pt-br, vi, id, hi, th).

Tools

Tool	Upstream endpoint	What it does
saju_calculate	POST /api/v1/calculate	Four Pillars (stem+branch+hanja), five-element distribution, Day Master, zodiac, from a solar birthdate.
saju_interpret	POST /api/v1/interpret	Full reading: Ten Gods (십신), hidden stems, Yongshin (용신), Daeun (대운), localized summaries.
saju_compatibility	POST /api/v1/compatibility	Two-person 궁합 score (0–100) with breakdown (element balance, Day Master relation, branch harmony/clash).
saju_daily	GET /api/v1/daily	Daily fortune snapshot (score + advice) for a Day Master and date.

Prerequisites

• Node.js 18+ (uses the built-in global fetch).
• A Saju API key. The free tier is 100 requests/day, no credit card.

Get a free API key

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

The response contains an api_key of the form sajuapi_free_.... Keep it secret — it is passed to the server via the SAJU_API_KEY environment variable, never hardcoded.

Install & build

npm install
npm run build      # compiles src/index.ts -> dist/index.js

Quick local check (lists the 4 tools, then exits):

SAJU_API_KEY="sajuapi_free_xxx" npm start

Register in Claude Desktop

Edit your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add (use the absolute path to the built dist/index.js):

{
  "mcpServers": {
    "saju": {
      "command": "node",
      "args": ["D:\\kunstudio-apps\\saju-mcp\\dist\\index.js"],
      "env": {
        "SAJU_API_KEY": "sajuapi_free_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The four saju_* tools appear in the tools menu.

Other MCP hosts (Cursor, Windsurf, custom clients) use the same shape: command: "node", args: ["<abs path>/dist/index.js"], and a SAJU_API_KEY env var.

Environment variables

Variable	Required	Default	Notes
SAJU_API_KEY	yes (for real calls)	(empty)	Your sajuapi_* key, sent as the X-API-Key header. Without it, every call returns 401 invalid_api_key.
SAJU_API_BASE	no	https://saju-api.pages.dev	Override the upstream base URL (e.g. for a staging deploy).

Example tool inputs

saju_calculate / saju_interpret:

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

(hour: -1 if the birth hour is unknown.)

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 (Day Master from a prior calculate/interpret call):

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

License

Proprietary — KunStudio. Wraps the Saju API; subject to that API's terms.