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 calculate my BaZi for birth date 1990-01-01 at 08:30" 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

GitHub Repository PyPI version License: MIT Python 3.12+ MCP Server

中文 | English

A Model Context Protocol (MCP) server for Chinese traditional calendar functions, built with Python 3.12 and lunar-python.

🚀 Quick Start (Recommended)

One-Command Launch with UVX

uvx bach-lunar-mcp

That's it! No installation, no virtual environment setup, no dependencies to manage. UVX will automatically download and run the server.

Configure in Your MCP Client

Cursor IDE

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

Claude Desktop

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

Cherry Studio

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

📦 PyPI Package: https://pypi.org/project/bach-lunar-mcp/
📖 Quick Start Guide: QUICKSTART_UVX.md

Features

🎋 BaZi Calculation - Calculate eight characters for fortune telling
📅 Calendar Conversion - Convert between solar and lunar calendars
🌙 Huangli Query - Chinese almanac with daily recommendations
🔮 Daily Fortune - Daily fortune and recommendations
⭐ Solar Terms - Query 24 solar terms for any year
🧮 Wu Xing Analysis - Five elements analysis from birth info

Installation

Prerequisites

Python 3.12+
uv package manager

Setup

Clone the repository:

git clone <repository-url> cd lunar-mcp-server

Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

Install project with dependencies:

uv sync

This will automatically:

Create a virtual environment with Python 3.12
Install all dependencies from pyproject.toml
Generate uv.lock for reproducible builds

Usage

As MCP Server

Configure in your MCP client (e.g., Claude Desktop):

{ "mcpServers": { "lunar-calendar": { "command": "uv", "args": ["run", "python", "-m", "src.server"], "cwd": "/path/to/lunar-mcp-server" } } }

Direct Usage

You can also use the helper functions directly:

# Run with uv uv run python -c " from src.utils import LunarHelper result = LunarHelper.solar_to_lunar(2024, 1, 1) print(result['lunar_date_chinese']) # 二〇二三年冬月二十 " # Calculate BaZi uv run python -c " from src.utils import LunarHelper result = LunarHelper.get_bazi(1990, 1, 1, 8, 30) print(result['bazi_string']) # 己巳丙子丙寅壬辰 "

Available Tools

1. bazi_calculate

Calculate BaZi (Eight Characters) for fortune telling.

Parameters:

birth_date: Birth date in YYYY-MM-DD format
birth_time: Birth time in HH:MM format

Example:

{ "birth_date": "1990-01-01", "birth_time": "08:30" }

2. calendar_convert

Convert between solar and lunar calendars.

Parameters:

date: Date in YYYY-MM-DD format
convert_to: "lunar" or "solar"
is_leap: Is leap month (optional)

Example:

{ "date": "2024-01-01", "convert_to": "lunar" }

3. huangli_query

Query Chinese almanac information for a specific date.

Parameters:

date: Date in YYYY-MM-DD format

Example:

{ "date": "2024-01-01" }

4. fortune_daily

Get daily fortune and recommendations.

Parameters:

date: Date in YYYY-MM-DD format

Example:

{ "date": "2024-01-01" }

5. jieqi_query

Query 24 solar terms for a specific year.

Parameters:

year: Year to query

Example:

{ "year": 2024 }

6. wuxing_analyze

Analyze Wu Xing (Five Elements) from birth information.

Parameters:

birth_date: Birth date in YYYY-MM-DD format
birth_time: Birth time in HH:MM format

Example:

{ "birth_date": "1990-01-01", "birth_time": "08:30" }

Development

Running Tests

# Quick functionality test uv run python quick_test.py # Run MCP server uv run python run_server.py # Test specific functionality uv run python -c "from src.utils import LunarHelper; print('✅ Import works!')" # Install dev dependencies (optional) uv add --dev pytest black mypy

Code Formatting

# Format code black src/ isort src/ # Type checking mypy src/

Dependencies

mcp: Model Context Protocol implementation
lunar-python: Chinese lunar calendar library
pydantic: Data validation and settings management

Contributing

Fork the repository
Create your feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

lunar-python - Excellent Chinese lunar calendar library
MCP - Model Context Protocol specification

Note: This is a traditional calendar tool for educational and entertainment purposes. Please use responsibly.

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

Lunar Calendar MCP Server

Lunar Calendar MCP Server

🚀 Quick Start (Recommended)

One-Command Launch with UVX

Configure in Your MCP Client

Cursor IDE

Claude Desktop

Cherry Studio

Features

Installation

Prerequisites

Setup

Usage

As MCP Server

Direct Usage

Available Tools

1. bazi_calculate

2. calendar_convert

3. huangli_query

4. fortune_daily

5. jieqi_query

6. wuxing_analyze

Development

Running Tests

Code Formatting

Dependencies

Contributing

License

Acknowledgments

Resources

New MCP Servers

Latest Blog Posts

MCP directory API