Which integrations are available for this server?

Integrated with Codecov for tracking test coverage of the lunar calendar MCP server codebase. Source code hosted on GitHub with CI/CD workflows for testing and code coverage tracking. Distributed as a Python package on PyPI, allowing installation and usage of the lunar calendar MCP server via pip. Uses Pytest for running unit tests and test coverage of the lunar calendar functionality. Python-based MCP server providing lunar calendar calculations, auspicious date checking, BaZi analysis, and Chinese cultural tradition tools through a Python API. Uses Ruff for code quality checking and linting during development.

How do I use Lunar Calendar MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Lunar Calendar MCP Server is tomorrow a good day to sign a contract?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

🌙 Lunar Calendar MCP Server

Traditional Chinese Lunar Calendar for AI Applications

Python Version License: MIT MCP Compatible codecov Tests PyPI version

📖 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

📚 Complete Features List →

🚀 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

📖 Detailed Usage Guide →

🛠️ 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

🔮 BaZi (八字) Tools (2)

calculate_bazi - Calculate Four Pillars of Destiny
calculate_bazi_compatibility - BaZi compatibility analysis

⚡ Advanced Tools (3)

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

📖 Complete API Reference →

🔮 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.

📖 Complete API Reference →

🏮 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

📖 Cultural Traditions Guide →

📝 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"] }

📖 More Examples →

🧪 Testing

# Run comprehensive MCP server tests ./scripts/test_mcp_final.sh # Run unit tests uv run pytest --cov

📖 Testing Guide →

📦 Publishing

This server is published to:

PyPI: pip install lunar-mcp-server
Smithery.ai: npx @smithery/cli install lunar-mcp-server (coming soon)

📖 Publishing Guide →

🛠️ 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/

📖 Development Guide →

📚 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.

⭐ Star on GitHub | 📦 View on PyPI | 🐛 Report Issues

Lunar Calendar MCP Server