Provides AI agents with offline lunar calendar, solar terms, and holiday context for 12 regions including China, Japan, and the US.
Also known as icyn12-tinker/icyndate, icyndate, @icyn/date-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 234
- Latest version
- 0.1.5
- Last commit
- Oct 10, 2026
- License
- MIT
What is Icyn Date MCP?
Icyn Date provides AI agents with offline lunar calendar, solar terms, and holiday context for 12 regions including China, Japan, and the US.
Summary generated from the project's README
About Icyn Date MCP server
Icyn Date provides a semantic date layer for AI agents and developers, offering offline access to lunar calendars, solar terms, and holiday data. It supports 12 regions including China, Japan, the US, and several others, with specific support for over 70 subdivisions. The server is designed for use with MCP clients like Claude Desktop or Cursor via a standard installation.
Users can query complex date information such as solar-to-lunar conversions, zodiac signs, and GanZhi details. The system includes precise solar term timings and regional holiday context, distinguishing itself by providing confidence levels and data sources for every holiday answer. It avoids guessing by returning specific error states when data is unavailable for a given year or region. The implementation is lightweight and relies on verified tables rather than runtime astronomy calculations.
What you can do with it
- 1Retrieve regional holiday contextAsk the agent to determine if a specific date in China is a public holiday or an adjusted workday.
- 2Identify solar termsFind out which of the 24 solar terms is currently active or when the next one will occur.
- 3Calculate workdays and long weekendsDetermine the number of workdays between two dates or find the next upcoming long weekend in a specific region.
Written from the project's README. Every use case is checked against a quote from it.
How to install Icyn Date MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Icyn Date MCP in Claude Code
$ claude mcp add icyndate -- npx -y @icyn/date-mcpInstall Icyn Date MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"icyndate": {
"command": "npx",
"args": [
"-y",
"@icyn/date-mcp"
]
}
}
}Install Icyn Date MCP in VS Code
.vscode/mcp.json
{
"servers": {
"icyndate": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@icyn/date-mcp"
]
}
}
}Install Icyn Date MCP in VS Code CLI
$ code --add-mcp '{"name":"icyndate","type":"stdio","command":"npx","args":["-y","@icyn/date-mcp"]}'Install Icyn Date MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"icyndate": {
"command": "npx",
"args": [
"-y",
"@icyn/date-mcp"
]
}
}
}Install Icyn Date MCP in Codex
$ codex mcp add icyndate -- npx -y @icyn/date-mcpInstall Icyn Date MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.icyndate] command = "npx" args = ["-y", "@icyn/date-mcp"]
Install Icyn Date MCP in Gemini CLI
$ gemini mcp add -s user icyndate npx -- -y @icyn/date-mcpInstall Icyn Date MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"icyndate": {
"command": "npx",
"args": [
"-y",
"@icyn/date-mcp"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableicyn12-tinker/icyndate is public and reachablegithub.com/icyn12-tinker/icyndate ↗Pass
- Package names this repository as its source@icyn/date-mcp names icyn12-tinker/icyndate as sourcenpmjs.com/package/@icyn/date-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-10github.com/icyn12-tinker/icyndate ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @icyn/date-mcpPass
- No critical advisory in the package or its dependencies100 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubicyndate
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 — subdivision holiday, resolvedRegion "DE-BY"
nextLongWeekend("CN", "2026-09-18", 7); // { start: "2026-10-01", end: "2026-10-07", days: 7 }
nextLunarDate(8, 15, "2026-09-18"); // next 中秋: { date: "2026-09-25", lunarYear: 2026, adjusted: false }
describe("2026-02-17", { region: "CN" });
// "2026-02-17 星期二,农历丙午马年正月初一,CN 放假:春节(第 3/9 天)。"
nextWorkday("CN", "2026-09-30"); // "2026-10-08"
workdaysBetween("CN", "2026-02-13", "2026-02-24");
- Solar ⇄ lunar for every day 1900-01-31 .. 2100-12-31 (
MAX_DATE; that last date falls inside lunar 2100 腊月, somonthLengthfor that month isnull— the table ends mid-month and the real length is unknown) - Year / day 干支, zodiac, Chinese month & day names, leap month handling (incl. the 2033 閏冬月 case)
- 24 solar terms as exact instants (second precision), current/next lookup, "is there a term on this day" at any UTC offset
- Workday / holiday queries for 12 regions, every answer tagged
official/baseline/predicted— never silently guessed - Zero dependencies, no runtime astronomy; ~480 KB of table data, of which only the lunar/solar-term tables and CN are in the default entry point — the other 11 regions and their 70+ subdivisions load only if you import them
Error model / 失败行为
- Functions that return an info object (
dayInfo,dateContext,holidays) never throw for missing data: they return{ available: false, reason }or an empty list. - Functions that return a scalar (
isWorkday,addWorkdays,nextWorkday,workdayCount) throwRangeErrorwhen the region-year is not covered. - Search functions (
nextLongWeekend,nextLunarDate) returnnullwhen nothing is found in range, and throw when data runs out. - Bad input (unknown region, malformed date, 2 月 30 日) always throws
TypeError/RangeError. Region codes are case-insensitive ("us-ca"="US-CA"); a code with no data at all still throws. - Prediction is forward-only. A year we have not entered is extrapolated only if it is after the
last entered year (
coverage(region).predictedFrom). Past uncovered years return{ available: false }rather than a guess — extrapolating the current 《放假办法》 backwards would invent history (清明/端午/中秋 became statutory only in 2008, 春节 runs 除夕..初三 only from 2025).
How it is verified / 验证方式
tools/gen_fixtures.py and tools/gen_solar_terms.py generate fixtures/lunar-1900-2100.json (73,384 rows) from two independent reference
implementations (sxtwl, lunar_python). The test suite converts every row in both directions.
Anything the two references disagree on is written to fixtures/lunar-disagreements.json and adjudicated by hand
(see NOTES.md). A release is blocked unless 100% of rows pass.
npm install
npm test # Node only
# the full release gate: build + tsc + tests + the CN cross-check
python3 -m pip install -r tools/requirements.txt # one pure-Python package
npm run check
The last step of npm run check verifies CN.json day-by-day against chinesecalendar. If that
package is missing it fails loudly rather than skipping — an unverified table must not look like a
passing gate.
Roadmap / 路线图
- Lunar core + 1900–2100 fixtures
- 24 solar terms with exact instants (two references agree within 55 s; spot-check against 紫金山天文台 published values before release)
- Holidays CN 2024–2026 official (incl. 调休), cross-checked day-by-day with
chinesecalendar; later years → statutory dayspredictedfrom lunar/solar-term rules (forward-only; earlier years are never guessed) - Holidays HK/MO/TW/JP/KR/VN/SG/US/GB/DE/FR 2024–2028 as
baseline(python-holidays rules), CNY dates cross-checked against our lunar table - Region time zones (DST-aware via Intl) so JP/KR/EU decide solar-term days in their own zone; region hierarchy (
US-CA,DE-BY,GB-SCT, 70+ subdivisions as diffs); holidaykind(public/federal/bank/substitute);previousWorkday/addWorkdays/workdayCount/holidaysBetween/isHolidayEve/nextLongWeekend; month & hour 干支,nextLunarDate(lunar birthdays);describe()one-sentence zh/en output for MCP -
dateContext()one-call API, canonical date input, confidence levels, BCP-47 names with guaranteeden+zh-Hans, canonical festival ids across regions, data version metadata, gracefulavailable: false - Upgrade baseline regions to
officialyear by year against gazettes (TW 補班, HK gazette, KR substitute days first) - "On this day" from Wikipedia (CC BY-SA, attributed per entry)
-
@icyn/datenpm package (esbuild ESM, per-region entry points, d.ts) ·@icyn/date-mcpMCP server (11 tools, stdio, smoke-tested end to end) -
icyndatepip package (same test vectors) - Hosted API
Repository layout / 目录
docs/ product & technical plan(产品与技术方案), worklog
fixtures/ reference test vectors (generated, committed)
tools/ fixture generators (Python, not shipped)
packages/core/ @icyn/date — the library
packages/mcp/ @icyn/date-mcp — MCP server
License
MIT for code and the derived lunar / solar-term tables. The baseline holiday tables for the eleven
non-CN regions are derived from python-holidays (MIT) — its
licence is reproduced in THIRD-PARTY-LICENSES, and each generated file records the exact version in
baseline_note. Other third-party data (Wikipedia, government holiday notices) keeps its own licence
and is attributed per entry.
Icyn Date MCP questions
How do I add Icyn Date MCP to Claude Code?
Run claude mcp add icyndate -- npx -y @icyn/date-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Icyn Date MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What regions are supported for holiday information?
The server supports 12 regions, including China (CN), Hong Kong (HK), Macau (MO), Taiwan (TW), Japan (JP), Korea (KR), Vietnam (VN), Singapore (SG), United States (US), United Kingdom (GB), Germany (DE), and France (FR).
Does the server work offline?
Yes, the server is designed to work offline using local table data.
How accurate is the lunar and solar term data?
Lunar and solar term data is verified for the years 1900–2100.