🐉 opc-chinese-calendar-mcp

MCP Server for Chinese traditional calendar — lunar dates, solar terms, zodiac, and daily fortune

Overview

opc-chinese-calendar-mcp is a pure TypeScript MCP (Model Context Protocol) server that provides AI agents with Chinese traditional calendar data. No external APIs — all calculations run locally.

Tools

| Tool | Description | |------|-------------| | get_lunar_date | Convert Gregorian date to Chinese lunar calendar (农历) with stem-branch (干支), zodiac, and five elements | | get_solar_terms | Get all 24 solar terms (二十四节气) for any year with cultural meanings | | get_daily_fortune | Daily fortune (黄历宜忌) with auspicious activities and traditional folk stories | | get_zodiac_info | Chinese zodiac sign details, personality traits, and compatibility |

Installation

npm install opc-chinese-calendar-mcp

Usage

As an MCP server

Add to your MCP client configuration:

{
  "mcpServers": {
    "chinese-calendar": {
      "command": "npx",
      "args": ["opc-chinese-calendar-mcp"]
    }
  }
}

Or install globally:

npm install -g opc-chinese-calendar-mcp
chinese-calendar-mcp

Example: get_lunar_date

Input:  { "year": 2025, "month": 1, "day": 29 }
Output: 农历 甲辰年 正月 初一 (Year of the Dragon, Wood element)

Example: get_solar_terms

Input:  { "year": 2025 }
Output: All 24 solar terms with dates, seasons, and cultural meanings

Example: get_daily_fortune

Input:  { "year": 2025, "month": 1, "day": 29 }
Output: Daily fortune with auspicious/inauspicious activities, lucky directions,
        gods in charge, and a traditional zodiac folk story

Example: get_zodiac_info

Input:  { "year": 2000 }
Output: 🐉 Dragon — personality, compatibility, five elements, folklore

Features

• Pure TypeScript — Zero external API dependencies, all calculations local
• Lunar Calendar — Accurate conversion for years 1900-2100 with leap month support
• 24 Solar Terms — Complete set with approximate dates, seasons, and meanings
• Stem-Branch (干支) — Heavenly Stems and Earthly Branches for year, month, and day
• Five Elements (五行) — Wood, Fire, Earth, Metal, Water classifications
• Zodiac Compatibility — 三合 (triple harmony), 六合 (secret friend), 相冲 (conflict), 相害 (harm), 相刑 (punishment)
• Daily Fortune (黄历) — Traditional auspicious/inauspicious activity recommendations
• Folk Stories — The Twelve Zodiac Race legend and cultural tales for each animal

Technical Details

• Built with @modelcontextprotocol/sdk v1.6+
• Input validation via zod schemas
• Lunar calendar data based on standard lookup tables (Hong Kong Observatory reference)
• Solar terms calculated using astronomical approximation (±1 day accuracy)
• Day stem-branch computed from known reference date (1900-01-01 = 甲戌日)

License

MIT

Related

• OPC MCP Factory — Build your own MCP servers
• zodiac-daily-pipeline — Automated zodiac daily poster pipeline