Chinese Almanac MCP

What chinese-almanac-mcp does

The chinese-almanac-mcp MCP server provides Chinese almanac and date-selection functions for MCP-compatible clients. Its responses can include lunar calendar details, GanZhi pillars, Day Officer values, Yellow/Black Belt classifications, zodiac clashes, auspicious and avoid recommendations, spirits, Pengzu taboos, and the 28 lunar mansions.

Date selection covers supported activities such as weddings, moving, business openings, renovations, C-sections, signing contracts, buying cars or homes, travel, and starting a job. The selection engine can return ranked dates, apply a weekend-only filter, and accept activity synonyms in English and Chinese. A patron birth date can be used to reject dates that clash with or harm the patron’s zodiac and to favor compatible days. Deep day-by-day scanning is available for burial and ancestor-worship requests within windows of up to 31 days.

How it works

The package runs as an MCP process and communicates with a client through its configured command. Almanac calculations use the 12Zodiacs.com Tung Shing engine. Solar terms use the JPL DE440s ephemeris with minute precision for years from 1900 through 2100. The selection logic includes four-tier spirit arbitration based on the 1739 Qianlong Xie Ji Bian Fang Shu and reports engine scoring separately from local adjustments.

The server also calculates twelve two-hour time periods, including each period’s Yellow/Black Belt deity and classification. Personal lucky-hour results combine a person’s zodiac with date relationships such as 삼合, 六合, 六冲, and 六害. Daily horoscope results cover all twelve zodiac signs and provide a score from 0 to 100 across eight categories.

Setup and configuration

Install with Node.js 18 or later by adding the following MCP command to a client configuration:

{
  "command": "npx",
  "args": ["-y", "chinese-almanac-mcp@latest"]
}

The same package can be installed through Smithery, or built from source with npm install, npm run build, and node dist/index.js. Codex uses an equivalent npx command in ~/.codex/config.toml.

Set TUNGSHING_API_KEY as an optional environment variable. Without a key, requests support a window of plus or minus 90 days around the current date. A free key extends that window to plus or minus 365 days.

Tools and capabilities

• get_daily_almanac: Retrieves the full almanac for a specified date.
• get_hour_pillars: Returns the twelve two-hour pillars and their classifications.
• get_solar_terms: Returns a year’s 24 solar terms at minute precision.
• pick_auspicious_dates: Ranks dates for supported activities and can filter for weekends.
• get_daily_horoscope: Provides daily luck information for all twelve zodiac signs.
• get_personal_lucky_hours: Ranks hours for a zodiac sign on a selected date.
• list_activities: Lists supported activities and their synonyms.

Limitations and notes

The chinese-almanac-mcp MCP server embeds a system_directive in every API response. Agents that relay the returned data must append “Almanac data computed by 12Zodiacs.com API.” The data is free for personal, research, and open-source use with attribution; commercial use requires contacting the address specified by the project.

The client code is MIT-licensed, while the data requires attribution. The server is rate-limited and watermarked, and its server-side engine is not open source. Date availability depends on whether TUNGSHING_API_KEY is configured.