Icyn Date MCP server

icyndate

Date context for AI agents and developers: lunar calendar, solar terms, holidays and "what does this day mean" — offline, verified, MIT. 给 AI Agent 和开发者的日期语义层：农历、节气、节假日、"这一天意味着什么"——离线、可验证、MIT。

Status: week 1. Lunar calendar, the 24 solar terms and the holiday layer (12 regions) are in;

lunar & solar terms verified for 1900–2100, CN holidays for 2024–2026.

状态：第一周。农历、二十四节气、节假日层（12 个地区）均已落地；农历与节气 1900–2100 全量验证，

中国大陆节假日 2024–2026 逐天对拍。

Install / 安装

npm i @icyn/date                       # library: lunar + solar terms + CN holidays (~90 KB)
import "@icyn/date/regions/all";       # opt in to the other 11 regions (+ subdivisions), or "@icyn/date/regions/JP"

npx -y @icyn/date-mcp                  # MCP server for Claude Desktop / Cursor / any MCP client

What works today / 现在能用的

One call:

import { dateContext } from "@icyn/date";

dateContext("2026-02-17", { region: "CN" });
// {
//   date: "2026-02-17", region: "CN",
//   civil:    { weekday: 2, isoWeek: 8, isoWeekYear: 2026, dayOfYear: 48, leapYear: false },
//   workday:  { available: true, kind: "public_holiday", isWorkday: false, confidence: "certain", source: "official",
//               holiday: { id: "spring-festival", festival: "lunar-new-year", name: { "zh-Hans": "春节", en: "Chinese New Year" }, dayIndex: 3, span: 9 },
//               meta: { region: "CN", data_version: "2026.09.18", verified_until: 2026, … } },
//   lunar:    { year: 2026, month: 1, day: 1, yearGanZhi: "丙午", zodiac: "马", monthName: "正月", dayName: "初一", … },
//   solarTerm:{ onThisDay: null, current: { name: { zh: "立春", en: "Beginning of Spring" }, at: "2026-02-03T20:01:51.000Z" }, next: { zh: "雨水", … } }
// }

Dates can be given as "2026-02-17", [2026, 2, 17], { year, month, day } or a Date (UTC fields). Every holiday answer carries source (official / baseline / predicted), confidence (certain / likely / uncertain) and data version metadata; a year we know nothing about comes back as { available: false, reason }, never a guess.

Pieces:

import { solarToLunar, lunarToSolar } from "@icyn/date";

solarToLunar("2026-02-17");
// { year: 2026, month: 1, day: 1, leap: false, yearGanZhi: "丙午", dayGanZhi: "…",
//   zodiac: "马", monthName: "正月", dayName: "初一", isLeapYear: false, monthLength: 30 }

lunarToSolar({ year: 2033, month: 11, day: 1, leap: true }); // [2033, 12, 22]

import { solarTerms, solarTermAt, solarTermOnDay } from "@icyn/date";
solarTermOnDay("2026-02-04");          // { name: { zh: "立春", en: "Beginning of Spring" }, at: 2026-02-03T20:01:51Z, … }
solarTermAt(new Date());               // { current, next } with exact instants
solarTerms(2027);                      // all 24 of the year

import { dayInfo, nextWorkday, workdaysBetween, holidays } from "@icyn/date";
dayInfo("2026-02-14", "CN");           // { kind: "adjusted_workday", isWorkday: true, source: "official", confidence: "certain", … }
dayInfo("2027-02-13", "CN");           // { kind: "weekend", source: "predicted", confidence: "uncertain", note: "Within the usual 调休 window…" }
regionsObserving("lunar-new-year", 2026); // [{ region: "HK", days: [...] }, { region: "KR", … }, …]
dayInfo("2026-01-06", "DE-BY");        // Heilige Drei Könige — subdivisi

Shortened. The full README is on GitHub.