Lunar Calendar MCP Server

中文 | English | 语言选择/Language

A Model Context Protocol (MCP) server for Chinese traditional calendar functions, built with Python 3.12 and lunar-python.

Features

🎋 BaZi Calculation - Calculate eight characters for fortune telling
📅 Calendar Conversion - Convert between solar and lunar calendars
🌙 Huangli Query - Chinese almanac with daily recommendations
🔮 Daily Fortune - Daily fortune and recommendations
⭐ Solar Terms - Query 24 solar terms for any year
🧮 Wu Xing Analysis - Five elements analysis from birth info

Installation

Prerequisites

• Python 3.12+
• uv package manager

Setup

1. Clone the repository:

git clone 
cd lunar-mcp-server

2. Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

3. Install project with dependencies:

uv sync

This will automatically:

• Create a virtual environment with Python 3.12
• Install all dependencies from pyproject.toml
• Generate uv.lock for reproducible builds

Usage

As MCP Server

Configure in your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "lunar-calendar": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.server"],
      "cwd": "/path/to/lunar-mcp-server"
    }
  }
}

Direct Usage

You can also use the helper functions directly:

# Run with uv
uv run python -c "
from src.utils import LunarHelper
result = LunarHelper.solar_to_lunar(2024, 1, 1)
print(result['lunar_date_chinese'])  # 二〇二三年冬月二十
"

# Calculate BaZi
uv run python -c "
from src.utils import LunarHelper
result = LunarHelper.get_bazi(1990, 1, 1, 8, 30)
print(result['bazi_string'])  # 己巳 丙子 丙寅 壬辰
"

Available Tools

1. bazi_calculate

Calculate BaZi (Eight Characters) for fortune telling.

Parameters:

• birth_date: Birth date in YYYY-MM-DD format
• birth_time: Birth time in HH:MM format

Example:

{
  "birth_date": "1990-01-01",
  "birth_time": "08:30"
}

2. calendar_convert