AngusHsu/lunar-mcp-server

📖 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
• ⚡ 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"

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 favorable
• find_good_dates - Find optimal dates
• get_daily_fortune - Daily fortune info
• check_zodiac_compatibility - Zodiac compatibility

🎊 Festival Tools (4)

• get_lunar_festivals - Festivals on date
• get_next_festival - Next upcoming festival
• get_festival_details - Festival information
• get_annual_festivals - Annual calendar

🌙 Moon Phase Tools (4)

• get_moon_phase - Moon phase info
• get_moon_calendar - Monthly calendar
• get_moon_influence - Activity influence
• predict_moon_phases - Phase predictions

📅 Calendar Conversion Tools (3)

• solar_to_lunar - Solar to lunar conversion
• lunar_to_solar - Lunar to solar conversion
• get_zodiac_info - Zodiac information

⚡ Advanced Tools (3)

• batch_check_dates - Check multiple dates
• compare_dates - Compare dates
• get_lucky_hours - Lucky hours of day

🏮 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

• - Practical examples and integration guides
• - Complete API documentation
• - Understanding Chinese calendar systems
• - Running and writing tests
• - Contributing to the project
• - Publishing to MCP registry

📄 License

MIT License - see file for details.

🙏 Acknowledgments

Built with dedication for preserving and sharing traditional calendar wisdom.