🌙 Lunar Calendar MCP Server
Traditional Chinese Lunar Calendar for AI Applications
20 Tools | BaZi (八字) | Chinese Zodiac | Five Elements | Moon Phases | Festivals | Auspicious Dates
📖 Overview
A comprehensive Model Context Protocol (MCP) server providing traditional Chinese lunar calendar information, auspicious date checking, and festival data based on Chinese cultural traditions.
Perfect for integrating ancient Chinese wisdom into modern AI applications through the Model Context Protocol.
✨ Features
- 🎯 Auspicious Date Analysis - Check favorable dates, find good dates, daily fortune, zodiac compatibility
- 🎊 Festival Information - Chinese festivals, next festival, festival details, annual calendars
- 🌙 Moon Phase Analysis - Accurate moon phases, location-aware, activity influence, monthly calendars
- 📅 Calendar Conversions - Solar-lunar conversion, zodiac information, cultural integration
- 🔮 BaZi (八字) Four Pillars - Birth chart analysis, destiny calculation, compatibility reading
- ⚡ Advanced Tools - Batch checking, date comparison, lucky hours
🚀 Quick Start in 30 Seconds
One-Line Installation
The fastest way to get started - no Python installation required:
# Install and run with uvx (recommended)
uvx lunar-mcp-server
Try It Out
Once running, you can immediately ask questions like:
- "Is today a good day for a wedding?"
- "When is the next Chinese festival?"
- "What's my Chinese zodiac sign if I was born in 1990?"
- "Find me 3 auspicious dates for moving house in March 2024"
- "Calculate my BaZi (八字) for 1990-05-15 14:30"
- "Check our BaZi compatibility for marriage"
Claude Desktop Integration
Add to your Claude Desktop configuration (claude_desktop_config.json):
{
"mcpServers": {
"lunar-calendar": {
"command": "uvx",
"args": ["lunar-mcp-server"]
}
}
}
Then restart Claude Desktop and start asking about lunar calendar information!
Alternative Installation Methods
# Using pip
pip install lunar-mcp-server
lunar-mcp-server
# Using uv
uv tool install lunar-mcp-server
lunar-mcp-server
# From source (for development)
git clone https://github.com/AngusHsu/lunar-mcp-server.git
cd lunar-mcp-server
uv sync
uv run lunar-mcp-server
🛠️ Available Tools
🎯 Auspicious Date Tools (4)
check_auspicious_date- Check if date is favorablefind_good_dates- Find optimal datesget_daily_fortune- Daily fortune infocheck_zodiac_compatibility- Zodiac compatibility
🎊 Festival Tools (4)
get_lunar_festivals- Festivals on dateget_next_festival- Next upcoming festivalget_festival_details- Festival informationget_annual_festivals- Annual calendar
🌙 Moon Phase Tools (4)
get_moon_phase- Moon phase infoget_moon_calendar- Monthly calendarget_moon_influence- Activity influencepredict_moon_phases- Phase predictions
📅 Calendar Conversion Tools (3)
solar_to_lunar- Solar to lunar conversionlunar_to_solar- Lunar to solar conversionget_zodiac_info- Zodiac information
🔮 BaZi (八字) Tools (2)
calculate_bazi- Calculate Four Pillars of Destinycalculate_bazi_compatibility- BaZi compatibility analysis
⚡ Advanced Tools (3)
batch_check_dates- Check multiple datescompare_dates- Compare datesget_lucky_hours- Lucky hours of day
🔮 BaZi (八字) - Four Pillars of Destiny
The BaZi feature provides authentic traditional Chinese fortune-telling based on birth date and time.
What is BaZi?
BaZi (八字), also known as "Four Pillars of Destiny" or "Eight Characters," is a traditional Chinese astrological system that analyzes a person's destiny and characteristics based on the cosmic energies present at their birth. Each person has four pillars (year, month, day, hour), and each pillar consists of two characters (a Heavenly Stem and an Earthly Branch), totaling eight characters.
Features
- Complete Four Pillars Analysis: Year (年柱), Month (月柱), Day (日柱), Hour (时柱)
- Heavenly Stems & Earthly Branches: All 10 stems (天干) and 12 branches (地支)
- Five Elements Analysis: Wood, Fire, Earth, Metal, Water distribution and balance
- Day Master (日主): Your core element and personality traits
- Life Stage Insights: How each pillar influences different life periods
- Element Recommendations: Favorable colors, directions, and career paths
- Compatibility Analysis: Relationship harmony based on element interactions
- Timezone Support: Accurate calculations for any timezone
Example Usage
from lunar_mcp_server.bazi import BaZiCalculator
calculator = BaZiCalculator()
# Calculate BaZi chart
result = await calculator.calculate_bazi("1990-05-15 14:30", timezone_offset=8)
print(f"Eight Characters: {result['eight_characters']}")
# Output: 庚午乙巳丙子乙未
print(f"Day Master: {result['day_master']['element']} {result['day_master']['polarity']}")
# Output: Day Master: Fire Yang
# Check compatibility
compat = await calculator.get_compatibility(
"1990-05-15 14:30",
"1992-08-20 10:00",
timezone_offset=8
)
print(f"Compatibility: {compat['compatibility_score']}/10 - {compat['compatibility_level']}")
# Output: Compatibility: 8/10 - Excellent
print(f"Relationship: {compat['element_relationship']}")
# Output: Wood generates Fire - supportive relationship
Understanding Your BaZi Chart
Each pillar represents different aspects of your life:
- Year Pillar (年柱): Ancestors, early life (0-15 years), inherited characteristics
- Month Pillar (月柱): Parents, youth (16-30 years), career development
- Day Pillar (日柱): Self, spouse, middle age (31-45 years), marriage
- Hour Pillar (时柱): Children, later life (46+ years), legacy
The Day Master (your day pillar's Heavenly Stem) represents your core self and is the most important element in BaZi analysis.
Element Relationships
BaZi uses two key cycles:
- Generation Cycle (生): Wood → Fire → Earth → Metal → Water → Wood
- Control Cycle (克): Wood → Earth → Water → Fire → Metal → Wood
These relationships determine compatibility and element balance in your chart.
🏮 Cultural Traditions
Based on traditional Chinese calendar systems:
- Lunar Calendar - Traditional lunar-solar calendar
- 12 Zodiac Animals - Rat, Ox, Tiger, Rabbit, Dragon, Snake, Horse, Goat, Monkey, Rooster, Dog, Pig
- Five Elements - Wood, Fire, Earth, Metal, Water
- 28 Lunar Mansions - Traditional stellar divisions
- Traditional Festivals - Spring Festival, Mid-Autumn, Dragon Boat, and more
📝 Example Usage
Python API
import asyncio
from lunar_mcp_server import LunarMCPServer
async def main():
server = LunarMCPServer()
# Check if date is auspicious for wedding
result = await server._check_auspicious_date(
date="2024-03-15",
activity="wedding",
culture="chinese"
)
print(f"Auspiciousness: {result['auspicious_level']}")
print(f"Score: {result['score']}/10")
asyncio.run(main())
Example Output
Here's what you can expect when checking an auspicious date:
{
"date": "2024-03-15",
"activity": "wedding",
"auspicious_level": "Very Auspicious",
"score": 8.5,
"lunar_date": {
"year": 2024,
"month": 2,
"day": 6,
"zodiac": "Dragon",
"element": "Wood"
},
"recommendations": [
"Excellent day for new beginnings",
"Dragon day brings good fortune",
"Wood element supports growth"
],
"lucky_hours": ["7-9 AM", "11 AM-1 PM", "5-7 PM"],
"favorable_colors": ["red", "gold", "purple"],
"things_to_do": ["Marriage ceremony", "Important contracts", "Grand openings"],
"things_to_avoid": ["Funerals", "Moving house", "Starting construction"]
}
🧪 Testing
# Run comprehensive MCP server tests
./scripts/test_mcp_final.sh
# Run unit tests
uv run pytest --cov
📦 Publishing
This server is published to:
- PyPI:
pip install lunar-mcp-server - Smithery.ai:
npx @smithery/cli install lunar-mcp-server(coming soon)
🛠️ Development
# Clone and setup
git clone https://github.com/AngusHsu/lunar-mcp-server.git
cd lunar-mcp-server
uv sync --dev
# Code quality
uv run black src/ tests/
uv run ruff check src/ tests/
uv run mypy src/
📚 Documentation
- 📖 Usage Examples - Practical examples and integration guides
- 📖 Tools Reference - Complete API documentation
- 📖 Cultural Traditions - Understanding Chinese calendar systems
- 📖 Testing Guide - Running and writing tests
- 📖 Development Guide - Contributing to the project
- 📖 Smithery Publishing - Publishing to MCP registry
📄 License
MIT License - see LICENSE file for details.
🙏 Acknowledgments
Built with dedication for preserving and sharing traditional calendar wisdom.