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
- Clone the repository:
git clone https://github.com/BACH-AI-Tools/lunar_mcp_server
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", "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 formatbirth_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 formatconvert_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 formatbirth_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
- 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_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.
Install Bach Lunar in Claude Desktop, Claude Code & Cursor
unyly install bach-lunarInstalls 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-mcpStep-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
Notion
Read and write pages in your workspace
by NotionLinear
Issues, cycles, triage — from Claude
by LinearGoogle Drive
Search and read your Drive files
by Googlemindsdb/mindsdb
Connect and unify data across various platforms and databases with [MindsDB as a single MCP server](https://docs.mindsdb.com/mcp/overview).
by mindsdbfulcradynamics/fulcra-context-mcp
Access personal health and biometric data (sleep stages, heart rate, HRV, glucose, workouts), calendar and location via the Fulcra Life API.
by fulcradynamicsrinadelph/Agent-MCP
Framework for building multi-agent systems that coordinate over MCP, with task management, shared context and RAG.
by rinadelphWhenLabs-org/when
Developer toolkit: stack detection for AI context files, port conflicts, .env schema validation, docs drift, dependency license audits and task timing.
by WhenLabs-orgBeltran12138/wecom-docs-mcp-server
WeCom (Enterprise WeChat) document operations via MCP: create, read, and edit Docs and Smartsheets (9 tools). Fills the doc-CRUD gap — existing WeCom MCP server
by Beltran12138freema/mcp-gsheets
Google Sheets API integration for reading, writing, formatting and sheet management.
by freemamattijsdp/dbt-docs-mcp
dbt-core (OSS) project metadata, model and column-level lineage, and dbt documentation.
by mattijsdpCompare 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
