Lunar Birthday MCP Server

Python MCP server for Korean lunar<->solar birthday conversion using Streamable HTTP.

Features

• Solar -> Lunar conversion (Korean standard)

• Lunar -> Solar conversion (including leap month)

• Streamable HTTP transport (/mcp)

• Structured success and error outputs

Related MCP server: shirabe-calendar-api

Calendar Standard

This project uses korean-lunar-calendar, based on Korean lunar calendar rules (KARI/KASI).

Prerequisites

• Python 3.11+

Installation

python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
pip install .[dev]

Run

python -m app.server

Default server endpoint: http://127.0.0.1:8000/mcp

For public/server deployment, set MCP_HOST=0.0.0.0.

Optional host/origin allow-list environment variables:

• MCP_ALLOWED_HOSTS (comma-separated, e.g. api.example.com:443,api.example.com:*)

• MCP_ALLOWED_ORIGINS (comma-separated, e.g. https://api.example.com,https://console.example.com)

DNS rebinding validation is relaxed by default to avoid Invalid Host header issues in reverse-proxy setups. To enforce localhost-only validation defaults, set:

• MCP_STRICT_HOST_VALIDATION=true

If you need tighter control in production, set both MCP_ALLOWED_HOSTS and MCP_ALLOWED_ORIGINS explicitly.

Verify with MCP Inspector

npx -y @modelcontextprotocol/inspector

Connect inspector to http://127.0.0.1:8000/mcp.

Development Checks

ruff check .
pytest -q

Windows Notes

• If your path contains non-ASCII characters, prefer pip install .[dev] over editable install.

• Bind to localhost for local development security.

Troubleshooting

• If a tool call returns an error payload, check code and hint fields.

• Ensure date range is within supported bounds returned by conversion_limits.

• If you still see Invalid Host header, set MCP_ALLOWED_HOSTS and MCP_ALLOWED_ORIGINS to your domain values, or disable strict mode by removing MCP_STRICT_HOST_VALIDATION=true.