lunar_mcp_server

This MCP server provides Chinese traditional calendar functionality built with Python 3.12 and the lunar-python library. It exposes tools for BaZi (Eight Characters) calculation, solar-lunar calendar conversion, daily almanac details, and more, enabling MCP clients to query calendar data and fortune-related insights through a consistent MCP interface. To use it, deploy the server and configure your MCP client to point to the uv-based command as shown in the installation notes. The server’s primary entrypoint runs the Python modules under src.server, which expose APIs for the various tools described in the project documentation. You can invoke the helper utilities or issue tool-specific requests via the provided MCP endpoints to obtain structured results for dates, births, and other calendar information.

Prerequisites:

• Python 3.12+ installed on your system
• uv package manager installed (see installation steps)

Installation steps:

1. Clone the repository:

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

2. Install uv (if not already installed):

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

3. Install project dependencies and set up the environment using uv:

uv sync

This will create a virtual environment with Python 3.12, install dependencies from pyproject.toml, and generate uv.lock for reproducible builds.

Running the MCP server:
- Start the server via uv (example):
```bash
uv run python -m src.server

Configure your MCP client to connect to the server using the provided mcp_config example (see above).

Tips and notes:

• Ensure Python 3.12+ is properly installed and available in your PATH.
• The uv tool creates a virtual environment; you may need to activate it or rely on uv to manage it automatically depending on your setup.
• If you encounter module import errors, verify that your working directory is correct and that the virtual environment contains the project’s dependencies.
• The server exposes multiple tools (bazi_calculate, calendar_convert, huangli_query, fortune_daily, jieqi_query, wuxing_analyze). Use the corresponding MCP requests to access these features.
• If using a custom path for the server module, adjust the uv run command accordingly (e.g., -m src.server might differ if your project structure changes).
• For production, consider pinning dependency versions via pyproject.toml and locking with uv.lock to ensure reproducible environments.