Command Palette

Search for a command to run...

UnylyUnyly
Весь каталог

Bach Lunar

БесплатноНе проверен

Chinese Lunar Calendar MCP Agent

GitHubEmbed

Описание

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

Установить Bach Lunar в Claude Desktop, Claude Code, Cursor

Рекомендуется · одна команда, все IDE
unyly install bach-lunar

Ставит в Claude Desktop, Claude Code, Cursor и VS Code — сам разбирается с npx, uvx и сборкой из исходников.

Впервые? Поставь CLI: curl -fsSL https://unyly.org/install | sh

Или настроить вручную

Выполни в терминале:

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

Пошаговые гайды: как установить Bach Lunar

FAQ

Bach Lunar MCP бесплатный?

Да, Bach Lunar MCP бесплатный — установка в пару кликов через Unyly без оплаты.

Нужен ли API-ключ для Bach Lunar?

Нет, Bach Lunar работает без API-ключей и переменных окружения.

Bach Lunar — hosted или self-hosted?

Self-hosted: сервер запускается локально на твоей машине командой из раздела установки.

Как установить Bach Lunar в Claude Desktop, Claude Code или Cursor?

Открой Bach Lunar на unyly.org, выбери вкладку своего клиента (Claude Desktop, Claude Code, Cursor) и нажми Install — конфиг сгенерируется автоматически, без правки JSON.

Похожие MCP

Compare Bach Lunar with

Не уверен что выбрать?

Найди свой стек за 60 секунд

Автор?

Embed-бейдж для README

Похожее

Все в категории productivity