{
  "markdown": "# China Calendar & Lunar MCP\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)\n[![Remote](https://img.shields.io/badge/Streamable%20HTTP-hosted%20free-success)](https://mcp.pianam.cn/calendar-mcp/mcp)\n\nChinese calendar tools for AI agents: **statutory public holidays & makeup-workday schedules** (2025–2026, per the State Council of China) plus accurate **solar-to-lunar calendar conversion** (lunar date, zodiac animal, ganzhi / heavenly-stems-earthly-branches).\n\n- **Try it in 30 seconds**: a free public MCP endpoint is already running — just paste the URL into your MCP client (no install, no API key).\n- **Or self-host**: a small FastMCP server; holiday data is bundled locally, lunar conversion uses the `sxtwl` ephemeris library (pure-Python `lunardate` fallback supported).\n\n## ⚡ Use the hosted endpoint (no setup)\n\n```\nhttps://mcp.pianam.cn/calendar-mcp/mcp\n```\n\nTransport: **Streamable HTTP** (MCP 2025-03-26 compatible). No authentication required.\n\n## 🔌 Client configuration\n\nAdd this to your MCP client's `mcpServers` configuration (Claude Desktop `claude_desktop_config.json`, Cursor `mcp.json`, Cline, Cherry Studio, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"calendar\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.pianam.cn/calendar-mcp/mcp\"\n    }\n  }\n}\n```\n\n> Clients that do not accept `\"type\": \"http\"` accept the same entry with just `\"url\"`.\n\n## 🧰 Tools\n\n| Tool | Parameters | Returns |\n|\n\n[![calendar-mcp MCP server](https://glama.ai/mcp/servers/boy-373/calendar-mcp/badges/score.svg)](https://glama.ai/mcp/servers/boy-373/calendar-mcp)\n\n---|---|---|\n| `query_holiday(date)` | `date`: solar date `YYYY-MM-DD`, e.g. `\"2026-10-01\"`. | Weekday, holiday name (if any), day type — public holiday off-day / makeup workday / normal workday / weekend — plus the lunar date for that day. |\n| `solar_to_lunar(year, month, day)` | `year`/`month`/`day`: solar date integers. | Lunar year/month/day, leap-month flag, lunar date string (Chinese), zodiac animal, and year/month/day ganzhi (干支). |\n| `list_holidays(year)` | `year`: integer year, e.g. `2026`. | All statutory holidays of the year: name, off-day count, date ranges, exact off dates and makeup-workday dates. |\n\n### Examples\n\n- \"2026-10-01 是节假日吗？\" → National Day holiday, with lunar date attached.\n- \"2026-02-17 农历是多少？\" → lunar date, zodiac, ganzhi.\n- \"列出 2026 年全部法定节假日和调休安排\" → full year schedule.\n\n## 📡 Data\n\n- **Holidays**: official holiday-arrangement notices issued by the General Office of the State Council of China (国务院办公厅). Bundled locally for 2025 and 2026; extend `HOLIDAY_DATA` to add more years.\n- **Lunar conversion**: [`sxtwl`](https://pypi.org/project/sxtwl/) (ShouWang calendar ephemeris, C extension). If `sxtwl` is unavailable the server automatically falls back to the pure-Python [`lunardate`](https://pypi.org/project/lunardate/) library (install it separately).\n- No external HTTP API and **no API key** is required.\n\n## 🐢 Self-hosting\n\n```bash\ngit clone https://github.com/boy-373/calendar-mcp.git\ncd calendar-mcp\npip install -r requirements.txt\npython server.py\n# listens on 127.0.0.1:8000 by default; override with:\n#   MCP_HOST=0.0.0.0 MCP_PORT=9000 python server.py\n# behind a reverse proxy, allow your public hostname:\n#   MCP_ALLOWED_HOSTS=\"your-domain.com,your-domain.com:*\" python server.py\n```\n\nThen point your MCP client at `http://127.0.0.1:8000/mcp`.\n\nYou can also run the server with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv venv && uv pip install -r requirements.txt\nuv run python server.py\n```\n\n## 🗂️ Files\n\n- `calendar_server.py` — the MCP server: holiday data, lunar conversion, FastMCP tool definitions.\n- `server.py` — standalone Streamable HTTP entry point (binds host/port, serves the MCP app at `/mcp`).\n- `requirements.txt` — Python dependencies.\n- `LICENSE` — MIT.\n\n---\n\n## 🇨🇳 中文说明\n\n中国万年历 MCP：**法定节假日 / 调休安排查询**（2025–2026，依据国务院办公厅通知）与**公历转农历**（农历年月日、闰月、生肖、干支）。\n\n**在线直连（免费、无需 Key）**：`https://mcp.pianam.cn/calendar-mcp/mcp`\n\n**工具**：\n\n- `query_holiday(date)`：查询某公历日期的节假日 / 调休安排，附带农历信息。\n- `solar_to_lunar(year, month, day)`：公历转农历，返回农历日期、闰月、生肖、干支。\n- `list_holidays(year)`：列出某年全部法定节假日放假与调休上班日期。\n\n节假日数据内置本地（2025、2026，可逐年扩展）；农历转换使用 `sxtwl` 历库，缺失时自动降级到纯 Python 的 `lunardate`；全程无需外部 API 与密钥。\n\n## 📄 License\n\n[MIT](LICENSE) © 2026 boy-373 (刘扶阳)\n",
  "bytes": 4387,
  "sha": "9d5016842ccce773b30b528bcca87f8b6747bfd65b8b243c434586ff3a88c932",
  "repo_slug": "boy-373/calendar-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_cn_pianam_mcp_calendar_mcp_ac61c10e/readme"
}