Date arithmetic, formatting, validation, and day-of-year via @skhatri/date-mcp (npx) — 8 tools

@skhatri/date-mcp v0.11.1 — 8-tool date/time MCP server

Install & run:

npm install --prefix /tmp/date-mcp @skhatri/date-mcp @modelcontextprotocol/sdk
# Entry: node_modules/@skhatri/date-mcp/dist/index.js (stdio transport)

Tools (8)

Verified trace (20 calls, 100% success, p50=0ms)

[1] current_datetime({}) → 2ms → "2026-06-20T03:10:47.059Z"
[2] current_datetime({timezone:"America/New_York"}) → 0ms → "2026-06-20T03:10:47.061Z"
[3] current_datetime({format:"locale",timezone:"Europe/Istanbul"}) → 46ms → "6/20/2026, 6:10:47 AM"
[4] format_date({date:"2026-06-20T10:30:00Z",format:"locale"}) → 0ms → "6/20/2026, 1:30:00 PM"
[5] format_date({date:"June 20, 2026",format:"ISO"}) → 1ms → "2026-06-19T21:00:00.000Z"
[6] format_date({date:"2026-06-20T10:30:00Z",format:"locale",timezone:"Asia/Tokyo"}) → 0ms → "6/20/2026, 1:30:00 PM"
[7] date_diff({date1:"2026-01-01",date2:"2026-06-20"}) → 1ms → "170 days"
[8] date_diff({date1:"..T08:00:00Z",date2:"..T14:30:00Z",unit:"hours"}) → 0ms → "6.5 hours"
[9] date_diff({...unit:"minutes"}) → 1ms → "45 minutes"
[10] add_time({date:"2026-06-20",amount:30}) → 0ms → "2026-07-20T00:00:00.000Z"
[11] add_time({date:"2026-06-20",amount:-7,unit:"days"}) → 0ms → "2026-06-13T00:00:00.000Z"
[12] add_time({date:"2026-06-20T10:00:00Z",amount:5,unit:"hours"}) → 0ms → "2026-06-20T15:00:00.000Z"
[13] is_valid_date({date:"2026-06-20"}) → 1ms → true
[14] is_valid_date({date:"not-a-date"}) → 0ms → false
[15] is_valid_date({date:"2024-02-29"}) → 0ms → true (leap year, correct)
[16] is_valid_date({date:"2025-02-29"}) → 0ms → true ⚠️ BUG: 2025 is NOT a leap year!
[17] days_since({date:"2026-01-01"}) → 0ms → 170
[18] days_between({start_date:"2026-01-01",end_date:"2026-12-31"}) → 0ms → 364
[19] day_of_year({date:"2026-06-20"}) → 0ms → 171
[20] day_of_year({}) → 1ms → 171

Key gotchas

1. ⚠️ `is_valid_date` DOES NOT CHECK LEAP YEARS — 2025-02-29 returns true despite 2025 not being a leap year. Uses lenient JS Date parsing that rolls over to March 1.
2. ⚠️ `timezone` param IGNORED in ISO format — current_datetime({timezone:"America/New_York"}) returns UTC, same as no-timezone call. Timezone only works when format: "locale" is specified.
3. ⚠️ `format_date` timezone IGNORED — timezone: "Asia/Tokyo" produces identical output to no-timezone call (both show server-local time). Only the server's TZ env var matters.
4. Natural date strings get LOCAL TZ offset — "June 20, 2026" → "2026-06-19T21:00:00.000Z" because the server applied UTC+3 offset.
5. `days_between` is exclusive of end date — Jan 1 to Dec 31 = 364 (not 365).
6. `date_diff` returns string with unit label — "170 days", "6.5 hours", "45 minutes" — not a raw number.
7. `add_time` supports negative amounts — subtract by passing negative amount.
8. `day_of_year` defaults to today when no date param given.
9. First `locale` format call ~46ms (Intl.DateTimeFormat JIT), rest sub-millisecond.
10. Different from timestamp-mcp (parse-only, returns UTC breakdown) and timezone-mcp (convert-only between IANA zones) — this one does arithmetic and validation.