saroday-mcp-server

@saroday/mcp-server

MCP (Model Context Protocol) server for Saroday — Korean Saju (사주) calculation and myeongni-hak (命理學) glossary lookup.

This MCP server lets Claude Desktop, Cline, Cursor, and any other MCP-compatible AI client perform accurate Korean Saju (Four Pillars of Destiny) calculation by calling the public Saroday API under the hood.

---

What it does

When connected, the AI client gains access to four tools:

Tool	Description
calculate_saju	Compute full Saju analysis (8 characters, sipseong, sinsal, hapchung, 12-unseong, yongshin, daeun) from birth date / time / gender.
lookup_glossary	Look up any of 80+ myeongni-hak terms (도화살, 천을귀인, 식신, 육합, etc.) with full Korean explanation.
get_daily_fortune	Today's fortune for one of 12 Western zodiac signs or 12 Chinese zodiac signs. Cached server-side, fast response.
discover_saroday_api	List available Saroday API endpoints and metadata.

Why this matters: ChatGPT, Claude, and other LLMs frequently miscalculate Saju when asked directly because manse-ryeok (萬歲曆) lookup and 절기 (jeolgi) boundary handling require precise data. This MCP delegates the math to a verified server while letting the AI focus on the interpretation.

---

Installation

Option A — npx (no install)

npx @saroday/mcp-server

Option B — global install

npm install -g @saroday/mcp-server
saroday-mcp

Option C — clone and run

git clone https://github.com/saroday/mcp-server.git
cd mcp-server
npm install
node index.js

Requires Node.js 18 or newer.

---

Configure Claude Desktop

Edit your Claude Desktop config file:

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

Add (or merge) the following:

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

Restart Claude Desktop. You should see "saroday" listed in the MCP servers panel (the plug icon in the input area).

Local development (running from cloned repo)

{
  "mcpServers": {
    "saroday": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/index.js"]
    }
  }
}

---

Configure Cline / Cursor / other MCP clients

Any MCP client that supports stdio transport works. Point it at the saroday-mcp binary or node index.js. See your client's docs for the exact config format.

---

Try it out

After connecting, ask Claude things like:

• "My birthday is March 15, 1992 at 10am. Calculate my Korean Saju."
• "What does 도화살 (dohwa-sal) mean in Korean fortune-telling?"
• "내 사주 봐줘. 1990년 5월 20일 음력 14시 여성."
• "제왕(jeokwang) 12-unseong이 뭐야?"

Claude will automatically invoke calculate_saju or lookup_glossary and give you a polished interpretation based on the structured data returned.

---

Environment variables

Variable	Default	Purpose
SARODAY_API_BASE	https://saroday.com	Override the API base URL (e.g., for self-hosted or staging environments).

---

Rate limits

The public Saroday API allows 100 requests per hour per IP for free use. Heavy users — apps shipping to many end-users, AI agents handling many concurrent users — should request an API key (coming soon) for higher quotas.

Contact: [email protected]

---

How it works

[User in Claude Desktop]
        ↓ types "내 사주 봐줘"
[Claude Desktop]
        ↓ calls calculate_saju via MCP stdio
[saroday-mcp (this package, runs locally)]
        ↓ HTTPS POST /api/v1/saju
[saroday.com server]
        ↓ runs verified manse-ryeok algorithm
[result JSON]
        ↑ flows back through the chain
[Claude] writes a beautiful Korean interpretation

This MCP package is a thin adapter — all calculation lives on Saroday's servers, so updates to the algorithm or glossary roll out without you having to upgrade the package.

---

Differentiators

• Manse-ryeok accuracy — handles 절기 (solar terms) boundaries that LLMs routinely get wrong (verified against @fullstackfamily/manseryeok library)
• 80+ glossary entries (~400 interpretation fields) — every sinsal, hapchung, sipseong, 12-unseong term has summary / meaning / positive / negative / practical-tip interpretation written in friendly Korean
• Korean myeongni-hak tradition — based on 적천수(滴天髓), 자평진전(子平真詮), 궁통보감(窮通寶鑑) references
• Three-channel exposure — same algorithm available as web service (saroday.com), public REST API (saroday.com/api/v1), and MCP server (this package). Pick the channel that fits your integration.

---

License

MIT

---

Support

• Web: https://saroday.com
• API docs: https://saroday.com/api/docs
• LLM-friendly index: https://saroday.com/llms.txt
• Email: [email protected]