home / mcp / lunar calendar mcp server

Lunar Calendar MCP Server

Provides traditional Chinese lunar calendar data, auspicious date checks, and festival information via MCP.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "angushsu-lunar-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "lunar-mcp-server"
      ]
    }
  }
}

This MCP server delivers traditional Chinese lunar calendar data, auspicious date analysis, festival information, moon phases, BaZi charts, and calendar conversions, enabling AI applications to integrate ancient wisdom with modern workflows.

How to use

Start the server using a simple command and then ask it practical questions about dates, festivals, BaZi calculations, and moon phases. You can check auspicious dates for events, look up upcoming festivals, convert between solar and lunar dates, view monthly moon calendars, and explore BaZi charts and compatibility.

How to install

# One-Line Installation
uvx lunar-mcp-server
```

# Alternative Installation Methods
```
pip install lunar-mcp-server
lunar-mcp-server
```

# From Source (development)
```
git clone https://github.com/AngusHsu/lunar-mcp-server.git
cd lunar-mcp-server
uv sync
uv run lunar-mcp-server

Additional configuration and usage notes

The following runtime command lines reflect how you typically start and run the server in development and production workflows. Use the same patterns when configuring MCP clients that integrate with this server.

{
  "mcpServers": {
    "lunar_calendar": {
      "type": "stdio",
      "name": "lunar_calendar_mcp",
      "command": "uvx",
      "args": ["lunar-mcp-server"]
    }
  }
}

Available tools

Auspicious Date Tools

Tools to check if a date is favorable, to find good dates, to retrieve daily fortune, and to assess zodiac compatibility.

Festival Tools

Tools to obtain lunar festivals for a date, find the next upcoming festival, get festival details, and view annual festival calendars.

Moon Phase Tools

Tools to get moon phase information, view monthly moon calendars, assess activity influence, and predict future moon phases.

Calendar Conversion Tools

Tools to convert between solar and lunar dates and retrieve zodiac information.

BaZi (八字) Tools

Tools to calculate the Four Pillars of Destiny, perform compatibility analysis, and generate BaZi charts.

Advanced Tools

Batch date checking, date comparison, and identification of lucky hours.