Lunar Calendar MCP Server

Analyzes whether a specific date is favorable for particular activities based on traditional Chinese calendar principles, including zodiac signs, five elements, lunar mansions, and other cultural factors. Returns a comprehensive score (0-10), auspiciousness level (very_good/good/neutral/poor/very_poor), and detailed analysis including what the date is good for and what to avoid.

Searches through a specified date range to identify the most auspicious dates for a particular activity. This tool evaluates each date in the range using traditional Chinese calendar methods and returns the top favorable dates ranked by their auspiciousness score. Ideal for planning important events like weddings, business openings, or travel. You can limit the number of results to get only the best options.

Provides comprehensive daily fortune analysis based on traditional Chinese almanac (通胜/黄历). Returns detailed information about the day's general energy, lucky directions, favorable colors, what activities are suitable, what to avoid, and overall fortune predictions. This gives a holistic view of the day's auspiciousness beyond specific activities.

Analyzes the compatibility between two dates based on their Chinese zodiac animals and five elements. This is traditionally used for checking compatibility between birth dates for relationships, partnerships, or selecting compatible dates for joint ventures. Returns compatibility score, detailed analysis of how the zodiac signs interact, and recommendations.

Retrieves all traditional festivals and cultural celebrations occurring on a specific date. For Chinese culture, this includes major festivals like Spring Festival (Chinese New Year), Mid-Autumn Festival, Dragon Boat Festival, and many others. Returns festival names, significance, traditional customs, and cultural importance of each celebration.

Finds the next upcoming traditional festival after a given reference date. Useful for planning ahead and understanding which cultural celebration is approaching. Returns the festival name, exact date when it occurs, days remaining until the festival, and brief information about its significance and traditions.

Provides in-depth information about a specific traditional festival including its historical origins, cultural significance, traditional customs and practices, symbolic meanings, typical foods, activities, and how it's celebrated. Perfect for learning about cultural traditions or planning authentic festival celebrations.

Generates a complete calendar of all traditional festivals for an entire year. Returns a chronologically ordered list of all cultural celebrations including their dates (both solar and lunar), names, and brief descriptions. Excellent for creating cultural event calendars, planning year-round celebrations, or understanding the annual rhythm of traditional observances.

Calculates precise moon phase information for a specific date and location using astronomical algorithms. Returns the moon phase name (new moon, waxing crescent, first quarter, waxing gibbous, full moon, waning gibbous, last quarter, waning crescent), illumination percentage, moon age in days, rise/set times, and position data. Location-aware calculations provide accurate local times.

Creates a comprehensive monthly calendar showing moon phases for each day of the month. Displays daily moon phase names, illumination percentages, and highlights important lunar events (new moons, full moons, quarters). Perfect for gardening, fishing, photography planning, or any activities influenced by lunar cycles. Provides both visual and detailed numerical moon data.

Analyzes how the moon's phase on a specific date influences various activities based on traditional beliefs and lunar wisdom. Different moon phases are believed to affect activities differently - e.g., new moons for new beginnings, full moons for completion, waxing moons for growth activities. Returns recommendations on whether the lunar phase supports or hinders the specified activity, with detailed explanations of the lunar influence.

Predicts and lists all major moon phase transitions (new moons, first quarters, full moons, last quarters) within a specified date range. Provides exact dates and times for each lunar phase event. Useful for planning activities around specific moon phases, scheduling lunar observations, or understanding the lunar cycle progression over time. Includes astronomical accuracy for reliable predictions.

Converts Gregorian (solar) calendar dates to traditional lunar calendar dates. Returns the corresponding lunar year, month, day, and leap month information if applicable. For Chinese calendar, also includes the year's zodiac animal, heavenly stem and earthly branch designations. Essential for finding lunar dates for traditional festivals, birth dates, or cultural events that follow the lunar calendar.

Converts traditional lunar calendar dates to Gregorian (solar) calendar dates. Accurately handles leap months and provides the exact solar date equivalent. Useful for determining when lunar-based festivals occur on the solar calendar, converting lunar birth dates to solar dates, or scheduling events based on lunar calendar information. Includes validation for proper lunar date formats.

Retrieves comprehensive zodiac information for a specific date. For Chinese zodiac, returns the zodiac animal (one of 12: Rat, Ox, Tiger, Rabbit, Dragon, Snake, Horse, Goat, Monkey, Rooster, Dog, Pig), associated element (Wood, Fire, Earth, Metal, Water), personality traits, compatible signs, lucky numbers, colors, and cultural significance. Provides both yearly and daily zodiac information based on the heavenly stems and earthly branches system.

Efficiently analyzes multiple dates simultaneously for a specific activity's auspiciousness. Processes up to 30 dates in a single request, returning scores and levels for each date. Also identifies and highlights the best and worst dates in the batch. This bulk analysis tool is perfect for quickly evaluating several potential dates for an event, comparing options across a non-continuous date range, or conducting comparative analysis of multiple candidates.

Performs comprehensive side-by-side comparison of multiple dates (up to 10) across various dimensions. For each date, returns auspiciousness analysis (if activity specified), moon phase details, festivals occurring, and zodiac information. Presents all information in an organized comparative format, making it easy to see differences and similarities. If an activity is specified, also provides a recommendation for which date is most suitable. Ideal for final decision-making between several good options.

Identifies the most auspicious hours within a specific day based on traditional Chinese time divisions (12 two-hour periods corresponding to the 12 zodiac animals). Each period is analyzed and scored for general favorability and activity-specific suitability. Returns detailed information for each time period including its Chinese name, zodiac animal, auspiciousness score, suitable activities, and recommendations. Perfect for timing important activities, meetings, ceremonies, or decisions within a chosen date for maximum favorable energy.

Calculates BaZi (八字, Eight Characters) or Four Pillars of Destiny based on birth date and time. BaZi is a traditional Chinese fortune-telling method that analyzes the cosmic energies present at birth through four pillars (year, month, day, hour), each with a heavenly stem and earthly branch. Returns comprehensive analysis including: the eight characters, day master element, elemental balance, personality insights, life stage influences, favorable colors/directions, and career suggestions. Essential for understanding one's destiny, personality, and life path in Chinese metaphysics.

Analyzes compatibility between two people based on their BaZi (Eight Characters) charts. Compares the four pillars and elemental compositions of both individuals to assess relationship harmony, strengths, and challenges. Returns compatibility score (0-10), compatibility level (Excellent/Good/Fair/Challenging), element relationship analysis, and detailed insights about how the two destinies interact. Traditionally used for marriage compatibility, business partnerships, or understanding relationship dynamics in Chinese culture.