{
  "markdown": "# Saju MCP — Korean Four Pillars & BaZi Astrology\n\n[![npm](https://img.shields.io/npm/v/saju-mcp)](https://www.npmjs.com/package/saju-mcp)\n[![node](https://img.shields.io/node/v/saju-mcp)](https://www.npmjs.com/package/saju-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=saju-mcp)\n[![license](https://img.shields.io/badge/license-proprietary-lightgrey)](#license)\n\nAn [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that\nwraps the **Saju API** — Korean Four Pillars of Destiny (사주팔자 / BaZi / 八字) — so\nany MCP-capable AI client (Claude Desktop, Cursor, VS Code, Windsurf, and custom\nagents) can compute, interpret, and compare Korean Saju charts directly in a\nconversation.\n\n```bash\nSAJU_API_KEY=\"sajuapi_free_xxx\" npx saju-mcp\n```\n\n> **30-second path:** [get a free key](#1-get-a-free-api-key-no-card) → [add the config](#3-register-in-your-mcp-client) → ask your AI client *\"calculate the saju for someone born 1990-05-15 14:00, male.\"*\n\n---\n\n## Why this MCP?\n\n- The only production-grade **Korean** Saju engine available as an MCP server.\n- **KASI-validated** lunar conversion (47,000+ days cross-checked, zero failures).\n- **Ten Gods (十神) + Yongshin (用神) + Daeun (大運)** — interpretive features absent\n  from generic Western astrology APIs that only return sun/moon signs.\n- **10 output languages**: Korean, English, Japanese, Chinese, Spanish,\n  Portuguese, Vietnamese, Indonesian, Hindi, Thai.\n- **Free tier: 100 requests/day, no credit card.** Freemium — start building today\n  and upgrade only when your app needs production volume.\n\nBacked by the live API at **https://saju-api.pages.dev**.\n\n## What it looks like in practice\n\nAsk your AI client a natural-language question; it calls `saju_calculate` and gets\nback structured data it can reason over. This is a **real, unedited** response from\nthe live API for `{ year: 1990, month: 5, day: 15, hour: 14, gender: \"M\", lang: \"en\" }`:\n\n```json\n{\n  \"pillars\": {\n    \"year\":  { \"stem\": \"경\", \"branch\": \"오\", \"stem_hanja\": \"庚\", \"branch_hanja\": \"午\" },\n    \"month\": { \"stem\": \"신\", \"branch\": \"사\", \"stem_hanja\": \"辛\", \"branch_hanja\": \"巳\" },\n    \"day\":   { \"stem\": \"경\", \"branch\": \"진\", \"stem_hanja\": \"庚\", \"branch_hanja\": \"辰\" },\n    \"hour\":  { \"stem\": \"계\", \"branch\": \"미\", \"stem_hanja\": \"癸\", \"branch_hanja\": \"未\" }\n  },\n  \"elements\": { \"wood\": 0, \"fire\": 2, \"earth\": 2, \"metal\": 3, \"water\": 1 },\n  \"day_master\": { \"stem\": \"경\", \"element\": \"metal\", \"polarity\": \"yang\" },\n  \"zodiac\": \"horse\",\n  \"tier\": \"free\",\n  \"remaining\": 99\n}\n```\n\nEvery response is returned to the model as both human-readable text **and**\n`structuredContent`, so agents can branch on `day_master.element`, `elements`, a\ncompatibility `score`, etc. without re-parsing prose.\n\n## Tools\n\n| Tool | Upstream endpoint | What it does |\n|------|-------------------|--------------|\n| `saju_calculate` | `POST /api/v1/calculate` | Four Pillars (stem+branch+hanja), five-element distribution, Day Master, zodiac, from a solar birthdate. |\n| `saju_interpret` | `POST /api/v1/interpret` | Full reading: Ten Gods (십신), hidden stems, Yongshin (용신), Daeun (대운), localized summaries. |\n| `saju_compatibility` | `POST /api/v1/compatibility` | Two-person 궁합 score (0–100) with breakdown (element balance, Day Master relation, branch harmony/clash). |\n| `saju_daily` | `GET /api/v1/daily` | Daily fortune snapshot (score + advice) for a Day Master and date. |\n\n---\n\n## Quickstart\n\n### 1. Get a free API key (no card)\n\nThe free tier is **100 requests/day, no credit card**:\n\n```bash\ncurl -X POST https://saju-api.pages.dev/api/v1/keys/create \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"dev@yourcompany.com\"}'\n```\n\nThe response contains an `api_key` of the form `sajuapi_free_...`:\n\n```json\n{\n  \"api_key\": \"sajuapi_free_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\n  \"tier\": \"free\",\n  \"daily_limit\": 100,\n  \"rps\": 1,\n  \"monthly_price_usd\": 0,\n  \"note\": \"Store this key safely — it is shown only once. Send with header `X-API-Key: <key>`.\"\n}\n```\n\n> The key is shown **only once** — store it now. It is passed to the server via the\n> `SAJU_API_KEY` environment variable, never hardcoded. (Disposable / `example.com`\n> email domains are rejected — use a real address.)\n\n### 2. (Optional) Smoke-test without an MCP client\n\n`npx` runs the server straight from npm — no clone, no local build:\n\n```bash\nSAJU_API_KEY=\"sajuapi_free_xxx\" npx -y saju-mcp\n```\n\nIt speaks MCP over stdio and exposes the four `saju_*` tools. Press `Ctrl-C` to exit.\n\n### 3. Register in your MCP client\n\nThe server is **stdio-based**, so every MCP client uses the same three pieces:\n`command: npx`, `args: [\"-y\", \"saju-mcp\"]`, and an `env` with your `SAJU_API_KEY`.\n\n<details open>\n<summary><strong>Claude Desktop</strong></summary>\n\nEdit your config file, then restart Claude Desktop:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"saju\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"saju-mcp\"],\n      \"env\": { \"SAJU_API_KEY\": \"sajuapi_free_your_key_here\" }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\nAdd to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project), then\nreload:\n\n```json\n{\n  \"mcpServers\": {\n    \"saju\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"saju-mcp\"],\n      \"env\": { \"SAJU_API_KEY\": \"sajuapi_free_your_key_here\" }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>VS Code (GitHub Copilot / MCP)</strong></summary>\n\nAdd to `.vscode/mcp.json` in your workspace:\n\n```json\n{\n  \"servers\": {\n    \"saju\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"saju-mcp\"],\n      \"env\": { \"SAJU_API_KEY\": \"sajuapi_free_your_key_here\" }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Windsurf</strong></summary>\n\nAdd to `~/.codeium/windsurf/mcp_config.json`, then refresh MCP servers:\n\n```json\n{\n  \"mcpServers\": {\n    \"saju\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"saju-mcp\"],\n      \"env\": { \"SAJU_API_KEY\": \"sajuapi_free_your_key_here\" }\n    }\n  }\n}\n```\n</details>\n\nRestart / reload your client. The four `saju_*` tools appear in its tool list.\n\n---\n\n## Example tool inputs\n\n`saju_calculate` / `saju_interpret`:\n\n```json\n{ \"year\": 1990, \"month\": 5, \"day\": 15, \"hour\": 14, \"gender\": \"M\", \"lang\": \"en\" }\n```\n\n(`hour: -1` if the birth hour is unknown.)\n\n`saju_compatibility`:\n\n```json\n{\n  \"person_a\": { \"year\": 1990, \"month\": 5, \"day\": 15, \"hour\": 14, \"gender\": \"M\" },\n  \"person_b\": { \"year\": 1992, \"month\": 8, \"day\": 3,  \"hour\": 9,  \"gender\": \"F\" },\n  \"lang\": \"en\"\n}\n```\n\n`saju_daily` (Day Master from a prior calculate/interpret call):\n\n```json\n{ \"day_master\": \"갑\", \"date\": \"2026-06-17\", \"lang\": \"en\" }\n```\n\n**Input bounds** (validated server-side, mirrors the API): `year` 1920–2050,\n`month` 1–12, `day` 1–31, `hour` -1–23, `gender` `\"M\"`|`\"F\"`, `lang` one of the 10\nsupported codes (default `ko`).\n\n## Environment variables\n\n| Variable | Required | Default | Notes |\n|----------|----------|---------|-------|\n| `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`. |\n| `SAJU_API_BASE` | no | `https://saju-api.pages.dev` | Override the upstream base URL (e.g. a staging deploy). |\n\n## Errors & troubleshooting\n\nWhen an upstream call fails, the tool returns an MCP **error result** (`isError: true`)\nwhose text is `Saju API error <status>: <body>` plus a hint. Common cases:\n\n| Symptom | HTTP status | Cause | Fix |\n|---------|-------------|-------|-----|\n| `401 invalid_api_key` | 401 | `SAJU_API_KEY` is missing, mistyped, or revoked. | Set the env var to a valid `sajuapi_*` key. [Get a free one.](#1-get-a-free-api-key-no-card) |\n| `429` (daily quota exceeded) | 429 | Free tier is 100 req/day, 1 rps. | Wait for the daily reset, or upgrade to a paid tier for production volume. |\n| `invalid_input` | 400 | A field is out of bounds (e.g. `month: 13`) or missing. | Check the input bounds above; the `reason` field names the offending field. |\n| Tools don't appear in the client | — | Client not restarted, or `npx` can't fetch the package. | Restart the client; run `npx -y saju-mcp` once in a terminal to confirm it starts. |\n| `non_json_response` | any | Upstream returned non-JSON (rare; network/proxy). | Retry; if persistent, check `SAJU_API_BASE` is correct. |\n\nKeys never appear in tool output or logs. If a key leaks, mint a new one — the old\none keeps its own quota and can be abandoned.\n\n## Develop / build from source\n\n```bash\ngit clone https://github.com/ghdejr11-beep/saju-mcp.git\ncd saju-mcp\nnpm install\nnpm run build      # compiles src/index.ts -> dist/index.js\nnpm run typecheck  # tsc --noEmit\n```\n\nRun the local build directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"saju\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/saju-mcp/dist/index.js\"],\n      \"env\": { \"SAJU_API_KEY\": \"sajuapi_free_your_key_here\" }\n    }\n  }\n}\n```\n\nRequires **Node.js 18+** (uses the built-in global `fetch`).\n\n## Upgrading to production\n\nThe free tier (100 req/day, 1 rps) is for building and evaluation. When your app\nships, higher-volume tiers are available on the same API — see\n**https://saju-api.pages.dev** for current plans and the key endpoint. Your code\nand config don't change; only the key does.\n\n## Related\n\n- **Korea Calendar API** — Korean public holidays, lunar↔solar conversion, the\n  gapja (간지) pillars and the 24 solar terms over REST. Pairs naturally with this\n  server when you need the raw calendar facts behind a saju reading:\n  https://korea-calendar-api.kunstudio.workers.dev\n\n## License\n\nProprietary — KunStudio. Wraps the Saju API; subject to that API's terms.\n",
  "bytes": 9782,
  "sha": "517471de934f2e7ba33645f76fa2f19026c043cd2c055d0b1a9928393e63b5d7",
  "repo_slug": "ghdejr11-beep/saju-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ghdejr11_beep_saju_mcp_e0c1b1bc/readme"
}