# Taiwan Almanac MCP Server (黃曆 MCP)

一個專為台灣用戶設計的黃曆 (Farmers' Almanac) MCP Server。提供每日宜忌、節氣、沖煞與吉日查詢功能。

## 🌟 Features

- **每日黃曆查詢 (`get_daily_almanac`)**: 查詢特定日期的農曆、宜忌、沖煞、財神方位等。
- **吉日搜尋 (`search_auspicious_days`)**: 針對特定活動（如嫁娶、入宅、動土）搜尋未來 30-90 天內的吉日。

## 🛠 Installation

### 1. Set up Environment

```bash
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### 2. Configuration

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tw-almanac": {
      "command": "/absolute/path/to/projects/mcp-tw-almanac/.venv/bin/python",
      "args": [
        "/absolute/path/to/projects/mcp-tw-almanac/src/server.py"
      ]
    }
  }
}
```

#### Dive (OpenClaw)

- **Type**: `stdio`
- **Command**: `[Path to Python]` (e.g. `/Users/simonliuyuwei/clawd/projects/mcp-tw-almanac/.venv/bin/python`)
- **Args**: `[Path to Server]` (e.g. `/Users/simonliuyuwei/clawd/projects/mcp-tw-almanac/src/server.py`)

## 📦 Data Source

- Uses `lunar_python` library (port of `lunar-javascript` by 6tail) for precise astronomical and cultural calculations.
- No external API keys required. Offline capable.

## 🇹🇼 Taiwan Localization

- Outputs in Traditional Chinese (繁體中文).
- Aligned with Taiwanese cultural customs (e.g. referencing 宜/忌).