cafe-mcp: Saju & BaZi (Four Pillars of Destiny) MCP server

Korean astrology (Saju, 사주) and Chinese BaZi (八字) for AI agents. Computed, not guessed. Give Claude, ChatGPT, Cursor or any MCP client a birth date and time. cafe-mcp returns the Four Pillars chart, Day Master, Five Elements balance, chart structure, favorable-element candidates and a manseryeok (만세력) calendar as structured, reproducible JSON from the CAFE engine. Your AI writes the reading in the user's language.

Why not just ask the LLM? A general model improvises the chart: the same birth data gives a different Day Master on different days, and solar-term boundaries, hidden stems and luck cycles are routinely wrong. cafe-mcp calculates them with an engine built since 2019 (3,000+ chart features, interpretation method reviewed by a PhD in Myeongri, favorable-element model validated at 91.1% accuracy). Same input, same chart, every time. All 6 tools are free. No API key.

---

Quick start

No API key, no local engine, no database. Two ways to connect:

1. Remote (no install): add a custom connector with this URL, e.g. in Claude (Settings > Connectors), ChatGPT (Developer mode) or any client that supports Streamable HTTP:

https://mcp.24plus.ai.kr/mcp

2. Local (stdio): Claude Desktop claude_desktop_config.json (Cursor: ~/.cursor/mcp.json, Claude Code: claude mcp add cafe-mcp -- npx -y @dangamsoft/cafe-mcp):

{
  "mcpServers": {
    "cafe-mcp": {
      "command": "npx",
      "args": ["-y", "@dangamsoft/cafe-mcp"]
    }
  }
}

Self-host the remote server: npx -p @dangamsoft/cafe-mcp cafe-mcp-http (env PORT, HOST, TRUST_PROXY=1 behind a proxy, RATE_LIMIT_PER_MIN).

What you can ask

• "Show my BaZi chart for 1990-01-15 10:30, male."
• "What is my Day Master, and which element am I missing?"
• "Is my chart hot or cold? Which element balances it?"
• "What are my favorable element (Yongshin) candidates, and why?"
• "What is today's day pillar?" / "When exactly does Lichun (입춘) start in 2027?"
• "Good days to move house next month?" (손없는날 / 황도일 flags)
• "내 사주 격국이랑 조후 봐줘" (Korean works too; the tools are language-neutral)

Works in Claude (web, desktop, mobile), Claude Code, ChatGPT, Cursor, Windsurf and any client that speaks MCP.

Tools (free, no key)

Tool	Returns
saju_chart	Four Pillars (四柱八字): stems and branches, Day Master (日干), Ten Gods (十神), hidden stems, Spirit Stars (神殺), Twelve Life Stages (十二運星)
ohaeng_balance	Five Elements (五行) distribution, dominant / weakest element
gyeokguk	Chart structure (格局) and Day Master strength (身强 / 身弱)
eumyang_johu	Yin-Yang and climate (陰陽 調候) balance across luck cycles (大運)
yongshin_candidates	Favorable element (用神) candidates from 5 classical methods (격국, 억부, 병약, 조후, 통관)
manse_calendar	Manseryeok (萬歲曆): day / month / year pillars, lunar dates, 24 solar terms (節氣) with exact start time (KST), Korean holidays, 손없는날 / 황도일, for a month (month: "2027-02") or a day (date: "2027-02-04"); no birth input

Every tool is read-only and returns structuredContent (with an outputSchema) plus a short text summary, so the model reads the numbers instead of parsing prose.

Input (chart tools)

field	example	notes
birth	1990-01-15T10:30	local time; legacy 199001151030 also accepted
sex	female / male	legacy gender 0/1 accepted
calendar	solar (default) / lunar	lunar_leap_month for leap months
rat_hour_rule	late (default) / early	야자시 / 조자시 (late vs early Rat hour)
year_boundary	lichun (default) / winter_solstice	입춘 / 동지 (year starts at Lichun or the winter solstice)
time_unknown	true	hour pillar marked as estimated
loc	259	births outside Korea (24Plus world-city ID); other IANA time zones are rejected rather than guessed

Errors return isError: true, a readable first text block, and a JSON second block {"error": {"code", "field?", "message"}} with codes invalid_input, rate_limited, timeout, backend_unavailable.

Resources & prompts: cafe://ontology (OWL 2 Turtle, CC BY 4.0) and the full_reading prompt.

Calculation tools stay free. The engine's final favorable-element decision (ML cross-validated) and full reports are part of the 24Plus service; a keyed yongshin_recommend tool may be added in a later minor version without changing these tools.

Custom backend: set CAFE_MCP_API_URL (the server POSTs to ${CAFE_MCP_API_URL}/try/panels; default https://24plus.ai.kr/api).

---

Why cafe-mcp

	LLM-only readings	Calculator-only servers	cafe-mcp
Chart math (pillars, hidden stems, solar terms)	improvised	computed	computed
Ten Gods, Spirit Stars, Twelve Life Stages	often wrong	sometimes	computed
Chart structure (格局) and favorable-element candidates	guessed	usually absent	classical rules, ML-validated engine
Korean Saju conventions (야자시, 입춘 / 동지, 손없는날)	no	rarely	yes, switchable
Output	prose	text	structuredContent + outputSchema
Setup	none	npm install	remote URL, no install (or npx)
Price	n/a	varies	free, no key

Saju or BaZi?

Korean Saju (사주명리학) and Chinese BaZi (八字命理) share the same chart and the same classical roots (子平眞詮, 滴天髓, 窮通寶鑑 and others). The differences are conventions: Korea commonly applies the late Rat hour (야자시) rule, starts the year at Lichun (입춘), and uses its own manseryeok and holiday calendar. cafe-mcp follows the Korean school by default and exposes those switches, so it serves both audiences. Names use Korean romanization with Hanja kept: Yongshin = 用神 (favorable element), Gyeokguk = 格局 (chart structure), Sinsal = 神殺 (Spirit Stars), Ilgan = 日干 (Day Master). See Notes on traditions.

What the MCP does not do

It does not write the reading. It returns the chart and the classical analysis; the client model interprets it in the user's language. It also does not return the engine's single final Yongshin decision (see the note above).

---

Ontology

• 1,711 RDF triples, SPARQL-queryable, W3C OWL 2 conformant
• Models:
  • 60갑자 (Sexagenary cycle)
  • 75 sinsal (special-star annotations)
  • 18 patterns: 정격 10 + 특수격 8
  • 5 yongshin types: 격국, 억부, 병약, 조후, 통관
  • 12 life stages (12운성)
• Grounded in 6 classical treatises:
  • 적천수 (Diqianshui)
  • 자평진전 (Zipingzhenquan)
  • 난강망 (Lanjiangwang)
  • 궁통보감 (Qiongtongbaojian)
  • 연해자평 (Yuanhaiziping)
  • 삼명통회 (Sanmingtonghui)

See ontology/ for module structure, SPARQL examples, and the integrated turtle file (cafe-ontology.ttl). The ontology is the public layer of the CAFE engine (Cross-weighted Analysis of the Five Elements), released under CC BY 4.0 for academic use, system integration and downstream development.

---

CAFE engine performance

The CAFE engine, the inference system this ontology models, operates inside the 24Plus platform. Validated performance on 5-class yongshin classification (목/화/토/금/수, 5-fold cross-validated):

Metric	Result
Accuracy	91.10%
F1-Score (Macro)	91.08%
Precision (Macro)	91.16%
Recall (Macro)	91.10%
ROC AUC (Macro)	97.76%

Random baseline = 20% (5 classes). 4.56x better than random. ML ensemble with weighted voting and probability calibration.

The engine itself remains proprietary; the ontology models the domain structure it operates on.

---

Note on East Asian Myeongli traditions

This MCP focuses on the Korean Myeongli (사주명리학) tradition, which shares its classical roots (子平眞詮 Zipingzhenquan, 滴天髓 Diqianshui, 窮通寶鑑 Qiongtongbaojian, 淵海子平 Yuanhaiziping, 三命通會 Sanmingtonghui, 欄江網 Lanjiangwang) with the Chinese BaZi (八字) tradition.

Romanization uses Korean Revised Romanization (e.g., Yongshin, Sinsal). Hanja (정자) is preserved throughout the ontology.

---

Documentation

• Ontology specification: formal OWL ontology with SPARQL examples
• Changelog
• 24Plus MCP docs (Korean)

---

Built by

Dangamsoft (단감소프트), a Korean AI company specializing in classical East Asian knowledge systems. The same engine powers the 24Plus Saju service.

---

Privacy

The server receives only the tool arguments (birth date and time, sex, calendar options, optional city ID). No accounts, no cookies, no conversation text. Birth data is not stored beyond a same-day result cache. Full policy: PRIVACY.md.

---

License

• Code (live since v0.6.0): Apache 2.0
• Public OWL ontology (ontology/): CC BY 4.0

The CAFE inference engine, scoring algorithms, ML model weights, and interpretation templates remain proprietary.

---

한국어 요약

cafe-mcp는 사주명리 계산을 AI 에이전트에 붙이는 MCP 서버입니다. Claude, ChatGPT, Cursor 등 MCP를 지원하는 클라이언트에 원격 URL(https://mcp.24plus.ai.kr/mcp) 하나만 등록하면 설치 없이 바로 쓸 수 있고, npx -y @dangamsoft/cafe-mcp로 로컬(stdio) 실행도 됩니다.

• 도구 6종 모두 무료, API 키 없음: 사주 원국(saju_chart), 오행 분포(ohaeng_balance), 격국(gyeokguk), 음양·조후(eumyang_johu), 용신 후보(yongshin_candidates), 만세력(manse_calendar: 일진·월주·년주, 음력, 절기 입절 시각, 공휴일, 손없는날·황도일)
• 야자시/조자시, 입춘/동지 기준, 음력·윤달, 시간 미상, 해외 출생지를 입력으로 지정할 수 있습니다.
• 결과는 structuredContent + outputSchema로 돌려주므로 모델이 문장을 파싱하지 않고 숫자를 그대로 읽습니다.
• 온톨로지(OWL 2, 1,711 트리플)는 CC BY 4.0, 코드는 Apache 2.0입니다. 엔진의 최종 용신 판정과 전체 리포트는 24Plus 서비스(https://24plus.ai.kr)에서 제공합니다.