# Lunar Calendar MCP Server
[](https://github.com/BACH-AI-Tools/lunar_mcp_server)
[](https://pypi.org/project/bach-lunar-mcp/)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[中文](README.cn.md) | **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
```bash
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
```json
{
"mcpServers": {
"lunar-calendar": {
"command": "uvx",
"args": ["bach-lunar-mcp"]
}
}
}
```
#### Claude Desktop
```json
{
"mcpServers": {
"lunar-calendar": {
"command": "uvx",
"args": ["bach-lunar-mcp"]
}
}
}
```
#### Cherry Studio
```json
{
"mcpServers": {
"lunar-calendar": {
"command": "uvx",
"args": ["bach-lunar-mcp"]
}
}
}
```
**📦 PyPI Package**: https://pypi.org/project/bach-lunar-mcp/
**📖 Quick Start Guide**: [QUICKSTART_UVX.md](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
1. **Clone the repository:**
```bash
git clone <repository-url>
cd lunar-mcp-server
```
2. **Install uv (if not already installed):**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
3. **Install project with dependencies:**
```bash
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):
```json
{
"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:
```bash
# 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"date": "2024-01-01"
}
```
### 4. fortune_daily
Get daily fortune and recommendations.
**Parameters:**
- `date`: Date in YYYY-MM-DD format
**Example:**
```json
{
"date": "2024-01-01"
}
```
### 5. jieqi_query
Query 24 solar terms for a specific year.
**Parameters:**
- `year`: Year to query
**Example:**
```json
{
"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:**
```json
{
"birth_date": "1990-01-01",
"birth_time": "08:30"
}
```
## Development
### Running Tests
```bash
# 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
```bash
# 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
1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [lunar-python](https://github.com/6tail/lunar-python) - Excellent Chinese lunar calendar library
- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol specification
---
**Note:** This is a traditional calendar tool for educational and entertainment purposes. Please use responsibly.
