Saju

You have access to a complete MCP server that analyzes Korean Saju fortune-telling. It automatically calculates the Eight Characters from birth data, provides fortune analysis, compatibility checks, calendar conversions, daily fortunes, and multi-decade fortune trends, all through an MCP-compatible interface you can query from your client.

How to use

To use this MCP server, connect via an MCP client to the integrated tools. You can perform comprehensive Saju analysis, check compatibility between two people, convert between solar and lunar calendars, retrieve daily fortunes, inspect 10-year fortune cycles, get fortune by time period, and adjust interpretation settings. Use these tools to build applications that deliver personalized fortune insights, life planning, or compatibility guidance.

How to install

# Prerequisites
node --version   # Node.js 18 or newer
npm --version    # npm available (yarn or pnpm also acceptable)

# Option 1: Automatic installation script (recommended)
curl -fsSL https://raw.githubusercontent.com/hjsh200219/fortuneteller/main/install.sh | bash

# Option 2: Manual installation
npm install -g @hoshin/saju-mcp-server

# Option 3: Using npx (no installation required)
npx @hoshin/saju-mcp-server

# Source/build and local development workflow (optional)
git clone https://github.com/hjsh200219/fortuneteller.git
cd fortuneteller
npm install
npm run dev
npm run build
npm start

# Alternatively, run in production from built dist (example)
node dist/index.js

• After installation, you can configure Claude Desktop to load the MCP server automatically using the standard MCP entry points shown for local development or npm/npx usage. Ensure the runtime environment has Node.js 18+ and npm, yarn, or pnpm available.

## Configuration and usage notes

The server exposes seven integrated tools that you can invoke through your MCP client. You can adjust interpretation settings, enable or tune different analysis methods, and switch between different school-of-thought weighting to tailor results.

## Troubleshooting and tips

If you encounter issues with time zone handling or date calculations, ensure you are providing birth dates and times in a supported format and use the calendar conversion tool to cross-check dates. For runtime errors, confirm Node.js 18+ is installed and that you are invoking the correct MCP command (for example, using npx to run the server or a local node invocation to run a built script). If a tool does not respond as expected, verify the server is running and your MCP client is configured to reach the correct entry point.

## Available tools

### analyze\_saju

Integrated Saju analysis tool that performs basic birth data calculation, fortune analysis, Yongshin (useful deity) assessment, school comparisons, and method selection.

### check\_compatibility

Evaluate compatibility between two birth data profiles and present matching indicators.

### convert\_calendar

Convert between solar and lunar calendars for dates from 1900 to 2200, including leap month support.

### get\_daily\_fortune

Retrieve detailed daily fortune for a specific birth profile on a target date.

### get\_dae\_un

Provide 10-year major fortune cycle information from birth data.

### get\_fortune\_by\_period

Return fortune across a chosen period type (year, month, hour, or multi-year span).

### manage\_settings

Get or set interpretation presets and custom weightings for the analysis engines.