io.github.yolstudio26-oss/saroday-mcp-server
Korean Saju (사주) Four Pillars calculation + 80+ myeongni-hak (命理學) glossary terms.
Open source Open in the app JSON README (API)
About
Korean Saju (사주) Four Pillars calculation + 80+ myeongni-hak (命理學) glossary terms.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- yolstudio26-oss
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.0
- Last push
- 2026-04-26T02:04:38Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:01:42
- Updated
- 2026-08-29 04:01:42
- Origin id
io.github.yolstudio26-oss/saroday-mcp-server
README
# @saroday/mcp-server
MCP (Model Context Protocol) server for [Saroday](https://saroday.com) — 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)
```bash
npx @saroday/mcp-server
```
### Option B — global install
```bash
npm install -g @saroday/mcp-server
saroday-mcp
```
### Option C — clone and run
```bash
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:
```json
{
"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)
```json
{
"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: contact@saroday.com
---
## 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: contact@saroday.com