Saju Fortune-Telling MCP Server
This MCP server performs Korean traditional Saju (Four Pillars of Destiny) fortune-telling — calculating birth charts and analyzing fortunes, compatibility, and calendar conversions.
analyze_saju — Integrated Saju analysis:
basicchart calculation,fortune(general/career/wealth/health/love),yongsinbeneficial-element analysis,school_compareacross 5 schools, andyongsin_method(strength/seasonal/mediation/disease)check_compatibility — Compares two people's Saju (each with birth date/time, gender, calendar, leap month) for a compatibility reading
convert_calendar — Converts dates between solar and lunar calendars (1900–2200) with leap-month support
get_daily_fortune — Provides a detailed daily fortune for a specified target date
get_dae_un — Returns 10-year major fortune cycles (Dae-un)
get_fortune_by_period — Time-based fortune by
year,month,hour, ormulti-year(with a count of years)manage_settings — Views or changes interpretation settings via presets (ziping/dts/qtbj/modern/shensha/balanced) or custom school weights
All tools accept birth date (YYYY-MM-DD), birth time (HH:mm), gender, calendar type, and leap-month flag as inputs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Saju Fortune-Telling MCP Server analyze my saju for career fortune: born March 15, 1990 at 10:30 AM, male"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🔮 사주 운세 MCP 서버 (Saju MCP Server)
한국 전통 사주팔자를 기반으로 운세를 분석하는 MCP(Model Context Protocol) 서버입니다.
A Model Context Protocol (MCP) server for Korean traditional Saju (Four Pillars of Destiny) fortune-telling.
✨ 주요 기능
사주팔자 계산: 생년월일시로부터 천간지지 8자 자동 계산 (진태양시 -30분 보정)
운세 분석: 성격, 직업운, 재물운, 건강운, 애정운 등 다양한 분석
궁합 분석: 두 사람의 사주 비교 및 궁합도 계산
음양력 변환: 양력 ↔ 음력 날짜 변환 지원 (1900-2200, 윤달 처리 포함)
일일 운세: 날짜별 상세 운세 제공
대운(大運): 10년 단위 큰 흐름 운세 조회
용신(用神) 분석: 색상, 방향, 직업 등 맞춤형 조언 제공
지장간 세력: 절기별 지장간 세력 계산으로 정밀한 분석
신살(神殺): 15개 신살 탐지 (원진살, 귀문관살 포함)
🆕 v1.2.0 신규 기능
7개 통합 도구: 15개 개별 도구를 7개로 최적화 (토큰 효율 40% 개선)
로컬 테이블: 1900-2200년 음양력 데이터 (외부 API 의존성 제거)
Zod 입력 검증: 런타임 타입 검증으로 에러율 40% 감소
date-fns 통합: 타임존 버그 제거 및 정밀한 날짜 처리
MCP SDK v1.18: 최신 프로토콜 및 성능 최적화
Smithery 지원: stateless export, npm 패키지 배포 병행
HTTP 서버 모드:
npm run start:http(Railway 배포용)
Related MCP server: Lunar Calendar MCP Server
🚀 시작하기
필수 요구사항
Node.js 18 이상
npm, yarn, 또는 pnpm
설치
자동 설치 스크립트 (가장 간편)
# 설치 스크립트 다운로드 및 실행
curl -fsSL https://raw.githubusercontent.com/hjsh200219/fortuneteller/main/install.sh | bash이 스크립트는 다음을 자동으로 수행합니다:
npm 패키지 전역 설치
Claude Desktop 설정 파일에 MCP 서버 자동 등록
기존 설정 백업
수동 설치
# npm으로 전역 설치
npm install -g @hoshin/saju-mcp-server
# 또는 npx로 직접 실행
npx @hoshin/saju-mcp-server소스에서 빌드
# 저장소 클론
git clone https://github.com/hjsh200219/fortuneteller.git
cd fortuneteller
# 의존성 설치
npm install
# 개발 모드 실행
npm run dev
# 프로덕션 빌드
npm run build
npm start🛠️ MCP 도구 (총 7개 - 통합 최적화)
1. analyze_saju
사주 분석 통합 도구 (기본 계산, 운세, 용신, 유파 비교, 용신 방법론).
분석 타입:
basic: 사주팔자 기본 계산fortune: 운세 분석 (general/career/wealth/health/love)yongsin: 용신 상세 분석school_compare: 5개 유파 비교 (자평명리, 적천수, 궁통보감, 현대명리, 신살중심)yongsin_method: 특정 용신 방법론 분석 (강약/조후/통관/병약)
{
birthDate: "1990-03-15",
birthTime: "10:30",
calendar: "solar",
isLeapMonth: false,
gender: "male",
analysisType: "basic" | "fortune" | "yongsin" | "school_compare" | "yongsin_method",
// fortune 타입용 옵션
fortuneType?: "general" | "career" | "wealth" | "health" | "love",
// school_compare 타입용 옵션
schools?: ["ziping", "dts", "qtbj", "modern", "shensha"],
// yongsin_method 타입용 옵션
method?: "strength" | "seasonal" | "mediation" | "disease"
}2. check_compatibility
두 사람의 궁합을 분석합니다.
{
person1: {
birthDate: "1990-03-15",
birthTime: "10:30",
calendar: "solar",
isLeapMonth: false,
gender: "male"
},
person2: {
birthDate: "1992-07-20",
birthTime: "14:30",
calendar: "solar",
isLeapMonth: false,
gender: "female"
}
}3. convert_calendar
양력과 음력을 변환합니다 (1900-2200 지원).
{
date: "2025-01-01",
fromCalendar: "solar",
toCalendar: "lunar",
isLeapMonth?: false
}4. get_daily_fortune
특정 날짜의 일일 운세를 제공합니다.
{
birthDate: "1990-03-15",
birthTime: "10:30",
calendar: "solar",
isLeapMonth: false,
gender: "male",
targetDate: "2025-01-01"
}5. get_dae_un
10년 단위 대운(大運) 정보를 조회합니다.
{
birthDate: "1990-03-15",
birthTime: "10:30",
calendar: "solar",
isLeapMonth: false,
gender: "male"
}6. get_fortune_by_period
시간대별 운세 통합 도구 (연운/월운/시운/연속).
기간 타입:
year: 연별 운세 (세운, 歲運)month: 월별 운세 (월운, 月運)hour: 시간대별 운세 (시운, 時運)multi-year: 연속 연도 운세
{
birthDate: "1990-03-15",
birthTime: "10:30",
calendar: "solar",
isLeapMonth: false,
gender: "male",
periodType: "year" | "month" | "hour" | "multi-year",
// 기간 지정 (periodType에 맞는 형식)
target?: "2025" | "2025-03" | "2025-01-01 14:00",
// multi-year 타입용 옵션
count?: 5 // 조회할 연도 개수 (기본값: 5)
}7. manage_settings
해석 설정 관리 도구 (조회/변경).
액션:
get: 현재 설정 조회set: 설정 변경 (프리셋 또는 커스텀)
{
action: "get" | "set",
// set 액션용 옵션
preset?: "ziping" | "dts" | "qtbj" | "modern" | "shensha" | "balanced",
// 또는 커스텀 가중치
custom?: {
ziping: 0.3, // 자평명리 가중치 (0.0-1.0)
dts: 0.2, // 적천수 가중치
qtbj: 0.2, // 궁통보감 가중치
modern: 0.2, // 현대명리 가중치
shensha: 0.1 // 신살중심 가중치
}
}📁 프로젝트 구조
fortuneteller/
├── src/
│ ├── index.ts # MCP 서버 진입점 (stdio)
│ ├── server-http.ts # HTTP 서버 진입점 (Railway 배포용)
│ ├── smithery.ts # Smithery stateless export
│ ├── core/ # 핵심 시스템
│ │ ├── server.ts # MCP 서버 초기화
│ │ ├── tool-definitions.ts # 7개 도구 정의
│ │ └── tool-handler.ts # 도구 라우팅
│ ├── tools/ # MCP 도구 구현
│ │ ├── analyze_saju.ts # 통합 사주 분석
│ │ ├── check_compatibility.ts
│ │ ├── convert_calendar.ts
│ │ ├── get_daily_fortune.ts
│ │ ├── get_dae_un.ts
│ │ ├── get_fortune_by_period.ts # 통합 시간대별 운세
│ │ └── manage_settings.ts # 통합 설정 관리
│ ├── lib/ # 핵심 로직
│ │ ├── saju.ts # 사주 계산 (진태양시 -30분 보정)
│ │ ├── calendar.ts # 음양력 변환 (로컬 테이블)
│ │ ├── fortune.ts # 운세 분석
│ │ ├── compatibility.ts # 궁합 분석
│ │ ├── dae_un.ts # 대운 계산
│ │ ├── yong_sin.ts # 용신 선정
│ │ ├── ten_gods.ts # 십성 계산
│ │ ├── sin_sal.ts # 신살 탐지 (15개)
│ │ ├── day_master_strength.ts # 일간 강약
│ │ ├── gyeok_guk.ts # 격국 결정
│ │ └── ... # 세운/월운/대운/일주 상세 분석 모듈
│ ├── data/ # 정적 데이터
│ │ ├── heavenly_stems.ts # 천간(天干) 10개
│ │ ├── earthly_branches.ts # 지지(地支) 12개, 지장간 세력
│ │ ├── wuxing.ts # 오행(五行) 상생상극
│ │ ├── solar_terms.ts # 24절기 진입점
│ │ ├── solar_terms_1900_2200.ts # 24절기 (JPL DE440 생성)
│ │ ├── lunar_table.ts # 음력 변환 진입점
│ │ ├── lunar_table_1900_2200.ts # 한국 음력 (JPL DE440 생성, KASI 일치)
│ │ ├── manselyeok_table.ts # 만세력 기준 테이블
│ │ └── longitude_table.ts # 전국 162개 시군구 경도
│ ├── schemas/ # Zod 스키마 정의
│ ├── utils/ # 유틸리티 (날짜 처리 등)
│ ├── benchmark/ # 성능 벤치마크
│ └── types/ # 타입 정의
│ └── index.ts
├── scripts/ # 검증·성능 테스트 스크립트
├── package.json
├── tsconfig.json
├── docker-compose.yml
├── railway.json # Railway 배포 설정
├── smithery.yaml # Smithery 마켓플레이스 설정
├── AGENTS.md # Claude Code 가이드
└── README.md🔧 개발
# 개발 모드 (hot reload)
npm run watch
# 린트 체크
npm run lint
# 코드 포맷팅
npm run format
# 테스트 실행
npm test
# API 문서 생성
npm run docs
# API 문서 로컬 서버 (http://localhost:8080)
npm run docs:serve📖 MCP 클라이언트 설정
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json에 다음 설정을 추가하세요:
npm 패키지 사용 (권장)
{
"mcpServers": {
"saju": {
"command": "npx",
"args": ["-y", "@hoshin/saju-mcp-server"]
}
}
}전역 설치 후 사용
npm install -g @hoshin/saju-mcp-server{
"mcpServers": {
"saju": {
"command": "saju-mcp-server"
}
}
}로컬 개발 (소스에서)
{
"mcpServers": {
"saju": {
"command": "node",
"args": ["/path/to/saju-mcp-server/dist/index.js"]
}
}
}🐳 Docker 지원
Docker로 실행
# 이미지 빌드
docker build -t saju-mcp-server .
# 컨테이너 실행
docker run -it --rm saju-mcp-server
# 또는 docker-compose 사용
docker-compose up -dSmithery를 통한 원클릭 설치
# Smithery CLI로 설치
npx @smithery/cli install saju-mcp-server --client claudeSmithery 마켓플레이스에서 더 쉽게 설치하고 관리할 수 있습니다.
📚 사주팔자 용어 설명
기본 구성 요소
천간(天干): 갑(甲), 을(乙), 병(丙), 정(丁), 무(戊), 기(己), 경(庚), 신(辛), 임(壬), 계(癸) - 10개
지지(地支): 자(子), 축(丑), 인(寅), 묘(卯), 진(辰), 사(巳), 오(午), 미(未), 신(申), 유(酉), 술(戌), 해(亥) - 12개
오행(五行): 목(木), 화(火), 토(土), 금(金), 수(水) - 상생상극 관계
십성(十星): 비견, 겁재, 식신, 상관, 편재, 정재, 편관, 정관, 편인, 정인
고급 분석 요소
지장간(支藏干): 지지 속에 숨어있는 천간 (정기, 중기, 여기)
신살(神殺): 15개의 길흉 지표 (천을귀인, 역마살, 도화살, 원진살, 귀문관살 등)
용신(用神): 사주의 균형을 맞추는 핵심 오행
격국(格局): 사주의 전체적인 패턴과 성향
대운(大運): 10년 단위의 큰 운세 흐름
진태양시(眞太陽時): 한국 표준시 -30분 보정 (정확한 사주 계산을 위함)
⚠️ 면책 조항
이 서비스는 전통 사주팔자를 기반으로 한 참고용 정보를 제공합니다.
의학적, 법률적, 재정적 조언이 아닙니다
중요한 결정은 반드시 전문가와 상담하시기 바랍니다
운세는 개인의 노력과 선택에 따라 달라질 수 있습니다
📄 라이센스
MIT License
👨💻 기여
이슈 제보 및 풀 리퀘스트를 환영합니다!
English
✨ Features
Saju (Four Pillars) Calculation: Automatic calculation of 8 characters from birth date and time (with -30min true solar time correction)
Fortune Analysis: Comprehensive analysis including personality, career, wealth, health, and love fortune
Compatibility Analysis: Compatibility calculation and comparison between two people
Calendar Conversion: Solar ↔ Lunar calendar conversion (1900-2200) with leap month support
Daily Fortune: Detailed daily fortune for specific dates
Dae-un (大運): 10-year major fortune cycle analysis
Yong-sin (用神) Analysis: Personalized advice on colors, directions, and careers
Ji-jang-gan Strength: Precise analysis with seasonal hidden stem strength calculation
Sin-sal (神殺): Detection of 15 special stars (including Won-jin-sal, Gwi-mun-gwan-sal)
🚀 Quick Start
Installation
Option 1: Automatic Installation Script (Recommended)
curl -fsSL https://raw.githubusercontent.com/hjsh200219/fortuneteller/main/install.sh | bashOption 2: Manual Installation
npm install -g @hoshin/saju-mcp-serverOption 3: Using npx (No Installation)
npx @hoshin/saju-mcp-serverClaude Desktop Configuration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"saju": {
"command": "npx",
"args": ["-y", "@hoshin/saju-mcp-server"]
}
}
}Restart Claude Desktop and start using the tools!
🛠️ Available Tools (7 Integrated Tools)
analyze_saju - Integrated Saju analysis (basic/fortune/yongsin/school_compare/yongsin_method)
check_compatibility - Analyze compatibility between two people
convert_calendar - Convert between solar and lunar calendars (1900-2200)
get_daily_fortune - Get daily fortune for specific date
get_dae_un - Get 10-year major fortune cycles
get_fortune_by_period - Get fortune by period (year/month/hour/multi-year)
manage_settings - Manage interpretation settings (get/set)
📚 Key Concepts
Basic Components
Heavenly Stems (天干): 10 stems - 甲乙丙丁戊己庚辛壬癸
Earthly Branches (地支): 12 branches - 子丑寅卯辰巳午未申酉戌亥
Five Elements (五行): Wood, Fire, Earth, Metal, Water
Ten Gods (十星): 10 relationship types
Advanced Analysis
Hidden Stems (支藏干): Hidden stems within branches
Special Stars (神殺): 15 auspicious/inauspicious indicators
Yong-sin (用神): Beneficial element for balance
Pattern (格局): Overall life pattern classification
Dae-un (大運): 10-year major fortune cycles
True Solar Time (眞太陽時): -30min Korea time correction
🐳 Docker Support
# Build image
docker build -t saju-mcp-server .
# Run container
docker run -it --rm saju-mcp-server
# Or use docker-compose
docker-compose up -d🔧 Smithery One-Click Install
# Install via Smithery CLI
npx @smithery/cli install saju-mcp-server --client claudeEasier installation and management through Smithery marketplace.
📖 Documentation
📙 Developer Guide - Project structure and development
📘 Architecture - System architecture overview
📗 Design Docs - Design decisions and principles
📕 Quality Score - Quality metrics tracking
🤝 Contributing
Issues and pull requests are welcome!
📄 License
MIT License
⚠️ Disclaimer
This service provides reference information based on traditional Saju fortune-telling.
Not intended as medical, legal, or financial advice
Please consult professionals for important decisions
Fortune can change based on personal effort and choices
Made with ❤️ for Korean traditional fortune-telling
Available Tools
7 toolsanalyze_sajuC
사주 분석 통합 (basic/fortune/yongsin/school_compare/yongsin_method)
Inputs: birthDate (required), birthTime (required), gender (required), analysisType (required), +5 more.
check_compatibilityD
두 사람 궁합 분석
Inputs: person1 (required), person2 (required).
convert_calendarC
양력↔음력 변환
Inputs: date (required), fromCalendar (required), toCalendar (required), isLeapMonth.
get_dae_unD
10년 대운
Inputs: birthDate (required), birthTime (required), gender (required), calendar, +1 more.
get_daily_fortuneD
일일 운세
Inputs: birthDate (required), birthTime (required), gender (required), targetDate (required), +2 more.
get_fortune_by_periodC
시간대별 운세 (year/month/hour/multi-year)
Inputs: birthDate (required), birthTime (required), gender (required), periodType (required), +4 more.
manage_settingsC
해석 설정 관리 (get/set)
Inputs: action (required), preset, custom.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have distinct purposes: analyze_saju for comprehensive birth chart analysis, check_compatibility for relationship matching, convert_calendar for date conversion, get_dae_un for 10-year cycles, get_daily_fortune for daily predictions, get_fortune_by_period for time-based fortunes, and manage_settings for configuration. However, get_daily_fortune and get_fortune_by_period could potentially overlap in some use cases (e.g., daily vs. hourly fortunes), but their descriptions clarify the scope.
All tools follow a consistent snake_case naming convention with clear verb_noun patterns: analyze_saju, check_compatibility, convert_calendar, get_dae_un, get_daily_fortune, get_fortune_by_period, and manage_settings. The naming is predictable and readable throughout the set.
With 7 tools, this server is well-scoped for fortune-telling and Saju analysis. Each tool serves a specific function in the domain, from core analysis (analyze_saju) to utilities (convert_calendar) and configuration (manage_settings). The count is neither too sparse nor bloated, fitting the purpose effectively.
The tool set covers key aspects of Saju fortune-telling: birth chart analysis, compatibility checks, calendar conversion, fortune predictions (daily, time-based, and long-term cycles), and settings management. A minor gap might be the lack of tools for historical data or advanced customization beyond basic settings, but core workflows are well-supported.
Maintenance
Related MCP Connectors
Korean Saju (Four Pillars) calculator: birth chart, day pillar, luck flow, monthly fortune
Korean Four Pillars (Saju/BaZi) calculator: pillars, elements, ten gods, sinsal, luck cycles.
Korean saju fortune MCP: natal chart, today/daily/yearly luck, compatibility, and saved profiles.
Korean saju (BaZi) chart calculator, daily zodiac fortunes, dream meanings, 2027 New Year fortune
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables traditional Chinese fortune-telling through BaZi (Four Pillars) analysis, including solar/lunar date conversion, Five Element balance calculations, Ten Gods deduction, and destiny interpretation for metaphysics applications.22 npmMIT
- AlicenseNot gradedqualityBmaintenanceProvides Chinese traditional calendar functions including BaZi calculation, solar-lunar calendar conversion, Huangli almanac queries, daily fortune readings, 24 solar terms, and Wu Xing (Five Elements) analysis.25 PyPIMIT
- AlicenseAqualityDmaintenanceEnables Korean Saju (Four Pillars of Destiny) calculation and myeongni-hak glossary lookup via MCP, allowing AI clients to compute accurate saju analysis and look up fortune-telling terms.466 npmMIT
- AlicenseAqualityBmaintenanceKorean Saju and Chinese BaZi (Four Pillars) computed by the CAFE engine: natal chart with Day Master and Ten Gods, Five Elements balance, chart structure (格局), yin-yang and climate, favorable-element candidates, and a manseryeok calendar with exact solar-term times. 6 read-only tools, no API key. Remote: https://mcp.24plus.ai.kr/mcp or npx -y @dangamsoft/cafe-mcp6520 npmApache 2.0