lich-viet-mcp

MCP server exposing the Vietnamese lunar calendar algorithm (Hồ Ngọc Đức / Jean Meeus 1998 at UTC+7) as tools for AI agents.

Lets Claude Desktop, Copilot, and other MCP-compatible AI clients answer Vietnamese lunar-calendar questions deterministically instead of hallucinating. Backed by the same algorithm powering Lịch Việt PWA — validated across 51,135 consecutive days (1960–2099) with 0 errors.

Quick start — Claude Desktop

Add this to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "lich-viet": {
      "command": "npx",
      "args": ["-y", "lich-viet-mcp"]
    }
  }
}

Restart Claude Desktop. You can now ask questions like:

• "Convert 1 May 2026 to Vietnamese lunar date" → Claude calls solar_to_lunar → returns Rằm tháng Ba năm Bính Tuất.
• "Is 1 May 2026 a Hoàng Đạo day?" → Claude calls check_hoang_dao.
• "What Vietnamese holidays fall on 20 October 2026?" → Claude calls get_vn_holidays.

Tools

| Tool | Input | Output | |---|---|---| | solar_to_lunar | {day, month, year} | {ld, lm, ly, leap, validated} | | lunar_to_solar | {lunar_day, lunar_month, lunar_year, is_leap?} | {d, m, y, validated} or {error} | | get_can_chi_day | {day, month, year} | {canChi, validated} e.g. "Ất Hợi" | | get_can_chi_year | {year} | {canChi, validated} e.g. "Bính Tuất 🐶" | | check_hoang_dao | {day, month, year} | {isHoangDao, validated} | | get_vn_holidays | {day, month, year} | {holidays: [{name, type, src}], validated} |

validated field: true when the input year is within the algorithm's validated range (1960–2099). Values outside that range are still computed but flagged validated: false.

Examples

Solar → Lunar

Input:  { "day": 1, "month": 5, "year": 2026 }
Output: { "ld": 15, "lm": 3, "ly": 2026, "leap": false, "validated": true }

→ "1 May 2026" is Rằm tháng Ba năm 2026 (full moon of the 3rd lunar month).

Year zodiac

Input:  { "year": 2026 }
Output: { "canChi": "Bính Tuất 🐶", "validated": true }

→ 2026 is the Year of the Dog (Bính Tuất).

Vietnamese holidays

Input:  { "day": 20, "month": 10, "year": 2026 }
Output: {
  "holidays": [{ "name": "🌸 Phụ nữ Việt Nam", "type": "holiday", "src": "duong" }],
  "validated": true
}

Local development

git clone https://github.com/bao-vn/lich-viet-pwa.git
cd lich-viet-pwa/mcp-server
npm install
npm test       # smoke test all 6 tools
npm start      # start the MCP stdio server (stdin/stdout)

Inspect tools interactively with:

npx @modelcontextprotocol/inspector node index.js

Algorithm & accuracy

• Source: Hồ Ngọc Đức port of Jean Meeus, Astronomical Algorithms (1998)
• Timezone: UTC+7 (105°E, Vietnamese official)
• Validated range: 1960–2099 (51,135 days, 0 errors vs. reference)
• Out-of-range inputs: still computed, flagged validated: false in response

Same algorithm as Lịch Việt PWA — the authoritative implementation.

Links

• PWA app: https://bao-vn.github.io/lich-viet-pwa/
• Source (all of it): https://github.com/bao-vn/lich-viet-pwa
• Business docs / PRD / ADRs: docs/business/
• Issue tracker: https://github.com/bao-vn/lich-viet-pwa/issues

License

MIT · © bao-vn