Command Palette

Search for a command to run...

UnylyUnyly
Browse all

Bach Lunar

FreeNot checked

Chinese Lunar Calendar MCP Agent

GitHubEmbed

About

Chinese Lunar Calendar MCP Agent

README

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.

Upstream: this repository is a maintained fork of lunar_mcp_server by Albert Huang, published on PyPI as bach-lunar-mcp. The original copyright notice is kept in LICENSE.

🚀 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 solar terms for a specific year
🧮 Wu Xing Analysis - Five elements analysis from birth info

Installation

Prerequisites

  • Python 3.12+
  • uv package manager

Setup

  1. Clone the repository:
git clone https://github.com/BACH-AI-Tools/lunar_mcp_server
cd lunar_mcp_server
  1. Install uv (if not already installed):
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. 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", "bach-lunar-mcp"],
      "cwd": "/path/to/lunar_mcp_server"
    }
  }
}

Direct Usage

You can also use the helper functions directly:

# Run with uv
uv run python -c "
from utils import LunarHelper
result = LunarHelper.solar_to_lunar(2024, 1, 1)
print(result['lunar_date_chinese'])  # 二〇二三年冬月二十
print(result['zodiac'])              # 兔
print(result['gan_zhi_year'])        # 癸卯
print(result['week_chinese'])        # 星期一
"

# Calculate BaZi
uv run python -c "
from 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 solar terms for a specific year.

Parameters:

  • year: Year to query

Example:

{
  "year": 2024
}

Known limitation: The current implementation only checks the 1st day of each month, so it may not return all 24 solar terms for a given year.

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

Verify the Installation

uv run python -c "from utils import LunarHelper; print('✅ Import works!')"

Install Dev Dependencies (Optional)

uv sync --extra dev

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

  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 file for details.

Acknowledgments

  • lunar_mcp_server by Albert Huang - the original project this fork is based on
  • 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.

from github.com/BACH-AI-Tools/lunar_mcp_server

Install Bach Lunar in Claude Desktop, Claude Code & Cursor

Recommended · one command, every IDE
unyly install bach-lunar

Installs into Claude Desktop, Claude Code, Cursor & VS Code — handles npx, uvx and build-from-source repos for you.

First time? Get the CLI: curl -fsSL https://unyly.org/install | sh

Or configure manually

Run in your terminal:

claude mcp add bach-lunar -- uvx bach-lunar-mcp

Step-by-step: how to install Bach Lunar

FAQ

Is Bach Lunar MCP free?

Yes, Bach Lunar MCP is free — one-click install via Unyly at no cost.

Does Bach Lunar need an API key?

No, Bach Lunar runs without API keys or environment variables.

Is Bach Lunar hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install Bach Lunar in Claude Desktop, Claude Code or Cursor?

Open Bach Lunar on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Related MCPs

Compare Bach Lunar with

Not sure what to pick?

Find your stack in 60 seconds

Author?

Embed badge for your README

Browse similar

All productivity MCPs