Saju Mcp

io.github.ghdejr11-beepPublished by GitHub account ghdejr11-beepv0.1.0Updated Oct 25, 2026

Korean Four Pillars of Destiny (Saju/Bazi): calculate, interpret, compatibility & daily fortune.

VerifiedSTDIODesktop onlyLocation & LifestyleAI & ML

Overview

AI-generated overview

A local MCP server that wraps the Saju API so an assistant can compute, interpret and compare Korean Four Pillars (Saju/BaZi) charts and daily fortunes.

What you can do
Calculate a chart from a solar birthdate: four pillars, five-element distribution, Day Master and zodiac, with optional interpretation of Ten Gods, hidden stems, Yongshin and Daeun, in ten output languages, returned as text and structured content for branching on fields such as element or score. Compare two people for a 0–100 compatibility score with a breakdown. Fetch a daily fortune snapshot (score and advice) for a Day Master and date.
When to use it
Useful when you want an AI client to produce Korean Saju/BaZi readings, compatibility comparisons or daily fortunes in conversation, without calling the upstream API yourself. It suits astrology hobby use and light prototyping rather than production volume on the free tier.
Requirements
Runs locally over stdio, typically via npx with Node.js 18 or newer. Requires a Saju API key in the SAJU_API_KEY environment variable, sent upstream as the X-API-Key header; without it calls return 401. Network access to the Saju API is needed. An optional SAJU_API_BASE variable overrides the upstream base URL.
Before you install
The API key is shown only once at creation and must be stored safely; if it leaks, mint a new one. Birth details (date, hour, gender) for the person or people being read are sent to the third-party Saju API. The free tier is limited to 100 requests per day at 1 request per second, and higher-volume tiers are paid.

Installation

In SourceWeft

  1. Open Saju Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Saju MCP — Korean Four Pillars & BaZi Astrology

[npm] [node] [MCP Registry] [license]

An MCP (Model Context Protocol) server that wraps the Saju API — Korean Four Pillars of Destiny (사주팔자 / BaZi / 八字) — so any MCP-capable AI client (Claude Desktop, Cursor, VS Code, Windsurf, and custom agents) can compute, interpret, and compare Korean Saju charts directly in a conversation.

bash
SAJU_API_KEY="sajuapi_free_xxx" npx saju-mcp

30-second path: get a free key → add the config → ask your AI client "calculate the saju for someone born 1990-05-15 14:00, male."

Why this MCP?

  • The only production-grade Korean Saju engine available as an MCP server.
  • KASI-validated lunar conversion (47,000+ days cross-checked, zero failures).
  • Ten Gods (十神) + Yongshin (用神) + Daeun (大運) — interpretive features absent from generic Western astrology APIs that only return sun/moon signs.
  • 10 output languages: Korean, English, Japanese, Chinese, Spanish, Portuguese, Vietnamese, Indonesian, Hindi, Thai.
  • Free tier: 100 requests/day, no credit card. Freemium — start building today and upgrade only when your app needs production volume.

Backed by the live API at https://saju-api.pages.dev.

What it looks like in practice

Ask your AI client a natural-language question; it calls saju_calculate and gets back structured data it can reason over. This is a real, unedited response from the live API for { year: 1990, month: 5, day: 15, hour: 14, gender: "M", lang: "en" }:

json
{  "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}

Every response is returned to the model as both human-readable text and structuredContent, so agents can branch on day_master.element, elements, a compatibility score, etc. without re-parsing prose.

Tools

ToolUpstream endpointWhat it does
saju_calculatePOST /api/v1/calculateFour Pillars (stem+branch+hanja), five-element distribution, Day Master, zodiac, from a solar birthdate.
saju_interpretPOST /api/v1/interpretFull reading: Ten Gods (십신), hidden stems, Yongshin (용신), Daeun (대운), localized summaries.
saju_compatibilityPOST /api/v1/compatibilityTwo-person 궁합 score (0–100) with breakdown (element balance, Day Master relation, branch harmony/clash).
saju_dailyGET /api/v1/dailyDaily fortune snapshot (score + advice) for a Day Master and date.

Quickstart

1. Get a free API key (no card)

The free tier is 100 requests/day, no credit card:

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

The response contains an api_key of the form sajuapi_free_...:

json
{  "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>`."}

The key is shown only once — store it now. It is passed to the server via the SAJU_API_KEY environment variable, never hardcoded. (Disposable / example.com email domains are rejected — use a real address.)

2. (Optional) Smoke-test without an MCP client

npx runs the server straight from npm — no clone, no local build:

bash
SAJU_API_KEY="sajuapi_free_xxx" npx -y saju-mcp

It speaks MCP over stdio and exposes the four saju_* tools. Press Ctrl-C to exit.

3. Register in your MCP client

The server is stdio-based, so every MCP client uses the same three pieces: command: npx, args: ["-y", "saju-mcp"], and an env with your SAJU_API_KEY.

Claude Desktop

Edit your config file, then restart Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
json
{  "mcpServers": {    "saju": {      "command": "npx",      "args": ["-y", "saju-mcp"],      "env": { "SAJU_API_KEY": "sajuapi_free_your_key_here" }    }  }}
Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project), then reload:

json
{  "mcpServers": {    "saju": {      "command": "npx",      "args": ["-y", "saju-mcp"],      "env": { "SAJU_API_KEY": "sajuapi_free_your_key_here" }    }  }}
VS Code (GitHub Copilot / MCP)

Add to .vscode/mcp.json in your workspace:

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

Add to ~/.codeium/windsurf/mcp_config.json, then refresh MCP servers:

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

Restart / reload your client. The four saju_* tools appear in its tool list.

Example tool inputs

saju_calculate / saju_interpret:

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

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

saju_compatibility:

json
{  "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):

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

Input bounds (validated server-side, mirrors the API): year 1920–2050, month 1–12, day 1–31, hour -1–23, gender "M"|"F", lang one of the 10 supported codes (default ko).

Environment variables

VariableRequiredDefaultNotes
SAJU_API_KEYyes (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_BASEnohttps://saju-api.pages.devOverride the upstream base URL (e.g. a staging deploy).

Errors & troubleshooting

When an upstream call fails, the tool returns an MCP error result (isError: true) whose text is Saju API error <status>: <body> plus a hint. Common cases:

SymptomHTTP statusCauseFix
401 invalid_api_key401SAJU_API_KEY is missing, mistyped, or revoked.Set the env var to a valid sajuapi_* key. Get a free one.
429 (daily quota exceeded)429Free tier is 100 req/day, 1 rps.Wait for the daily reset, or upgrade to a paid tier for production volume.
invalid_input400A field is out of bounds (e.g. month: 13) or missing.Check the input bounds above; the reason field names the offending field.
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.
non_json_responseanyUpstream returned non-JSON (rare; network/proxy).Retry; if persistent, check SAJU_API_BASE is correct.

Keys never appear in tool output or logs. If a key leaks, mint a new one — the old one keeps its own quota and can be abandoned.

Develop / build from source

bash
git clone https://github.com/ghdejr11-beep/saju-mcp.gitcd saju-mcpnpm installnpm run build      # compiles src/index.ts -> dist/index.jsnpm run typecheck  # tsc --noEmit

Run the local build directly:

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

Requires Node.js 18+ (uses the built-in global fetch).

Upgrading to production

The free tier (100 req/day, 1 rps) is for building and evaluation. When your app ships, higher-volume tiers are available on the same API — see https://saju-api.pages.dev for current plans and the key endpoint. Your code and config don't change; only the key does.

Related

  • Korea Calendar API — Korean public holidays, lunar↔solar conversion, the gapja (간지) pillars and the 24 solar terms over REST. Pairs naturally with this server when you need the raw calendar facts behind a saju reading: https://korea-calendar-api.kunstudio.workers.dev

License

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

Source: README.md at commit e19b578

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.