Lunar Calendar

You have a Model Context Protocol (MCP) server that provides Chinese traditional calendar functions. It offers BaZi calculations, solar and lunar calendar conversions, almanac data, daily fortunes, solar terms, and Wu Xing analysis, all accessible through MCP clients. This server makes it easy to add calendar intelligence to your applications and tools without building the calendar logic from scratch.

How to use

Use the server with an MCP client by running the provided MCP host process and connecting your client to it. You can start a single-command instance via UVX, or run the server directly through the MCP interface you prefer.

uvx bach-lunar-mcp

Configure your MCP client to connect to the server with one of these examples. Each configuration points the client to the same underlying MCP server via the same launcher, so pick the client you use and adjust the fields accordingly.

{
  "mcpServers": {
    "lunar-calendar": {
      "command": "uvx",
      "args": ["bach-lunar-mcp"]
    }
  }
}

If you prefer a direct approach without a ready-made launcher, you can run the server indirectly through the MCP interface of your client by using the equivalent command path. For example, you can start the server via a Python module path using the MCP runner configured in your client, and then communicate with it through the MCP protocol as you would with any other MCP server.

How to install

Prerequisites you need before installation are straightforward: Python 3.12 or newer and the UV package manager used to run MCP servers.

# Prerequisites
python3 --version
# Ensure you have Python 3.12+ installed

# Install the UV package manager if you don’t have it yet (example shown for a typical environment)
curl -LsSf https://astral.sh/uv/install.sh | sh

Installation steps you can follow to prepare and run the server in your environment are:

• Clone the project repository
• Install the UV runtime and dependencies
• Use UV to synchronize and install the necessary packages for reproducible builds

# 1) Clone the project repository
git clone <repository-url>
cd lunar-mcp-server

# 2) Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3) Install project with dependencies
uv sync

The install step creates a suitable virtual environment with Python 3.12, installs all dependencies listed in the project configuration, and generates a lockfile for reproducible builds.

Additional notes

The server exposes a suite of calendar-related capabilities you can leverage from your MCP clients, including:

• BaZi Calculation for fortune telling
• Calendar Conversion between solar and lunar calendars
• Huangli (almanac) queries for daily guidance
• Daily fortune and recommendations
• Solar terms by year
• Wu Xing analysis from birth information If you plan to work with a client, you can run the server using the MCP launcher command from your client configuration or start it directly using the MCP runner in your environment.

Recommended next steps include trying a quick local test by launching the server with UVX and then issuing requests from your MCP client to verify the output for a few sample dates.

Available tools

bazi_calculate

Calculate BaZi (Eight Characters) for fortune telling using birth date and birth time.

calendar_convert

Convert between solar and lunar calendars with options for date and leap month.

huangli_query

Query Chinese almanac information for a specific date.

fortune_daily

Get daily fortune and recommendations for a given date.

jieqi_query

Query 24 solar terms for a specific year.

wuxing_analyze

Analyze Wu Xing (Five Elements) from birth information.