Convert and compare dates and times across any timezone with flexible, locale-aware formatting. Ad…
ai.smithery/JMoak-chrono-mcp (MCP Server)
ai.smithery/JMoak-chrono-mcp is an MCP server that converts and compares dates and times across time zones, using flexible, locale-aware formatting. It supports time math at scale and returns temporal context in every response.
🛠️ Key Features
Convert and compare dates/times across time zones
Flexible, locale-aware formatting
Batch processing: up to 100,000 timestamps per single tool call
The MCP server for time math at scale. Batch-crunch up to 100,000 timestamps in a single tool call, speak the industry's temporal interchange standards (RFC 9557 IXDTF, RFC 5545 RRULE, ISO 8601 repeating intervals), and give your agent a passive sense of passing time on every response. Powered by Luxon, DST-correct by construction, and every limit is benchmark-backed.
LLMs are famously bad at time: they miscount weekdays, lose track of elapsed time between turns, and fall apart on DST math. chrono-mcp fixes all three — and does it at bulk scale, in the formats the rest of the industry already speaks.
Bulk by design - 10,000 calculations per request for per-item operations; 100,000 timestamps for stats, which returns pure aggregates. Every cap is proven by a benchmark you can run yourself (npm run bench) — per-item ops finish in under 100ms at the cap, 100k-item stats in ~460ms
RFC 9557 (IXDTF) Interchange - All datetime inputs accept bracketed IANA zone annotations (2026-08-09T15:00:00-04:00[America/New_York]) with Temporal-compatible offset-consistency validation, plus an ixdtf output format — the serialization standard of the JS Temporal API
Recurrence Expansion - expand turns RFC 5545 RRULEs (the format Google Calendar, Outlook, and Apple Calendar store) and ISO 8601 repeating intervals into concrete occurrences — DST-correct, window-bounded, with explicit truncation reporting
Temporal Context Envelope - Every tool response carries a compact trailing line with the current time, weekday, elapsed time since the agent's previous call, session age, and tzdb version — passive time-awareness on every interaction
Batch Error Isolation - One bad timestamp doesn't sink a 10,000-item batch: invalid entries are skipped and reported (invalid_count + samples), never silently dropped
Token-Optimized Output - Dynamically shaped responses that maximize information density while minimizing token usage
Global Timezone Support - All IANA timezone identifiers, with ISO, RFC2822, SQL, and locale-aware formatting
Type Safety - Zod validation on every parameter, MCP-compliant errors, strict TypeScript throughout
Documentation
API Reference - Complete documentation of all tools, parameters, and examples
Architecture - System architecture and design principles
Perform time arithmetic at any scale — single conversions to 100k-item batch analysis.
Operations:
add - Add duration to a datetime
subtract - Subtract duration from a datetime
diff - Calculate simple difference in various units
duration_between - Detailed duration breakdown between two times
stats - Statistical analysis of time series and durations (up to 100,000 timestamps per call)
sort - Sort timestamps chronologically
expand - Expand an RFC 5545 RRULE or ISO 8601 repeating interval into occurrences
Every operation accepts arrays as well as single values, with interaction_mode controlling how base and compare arrays combine (pairwise, cross_product, single_to_many, …). Invalid entries in a batch are skipped and reported — never silently dropped, never fatal.
Also accepts ISO 8601 repeating intervals (R5/2026-03-01T14:00:00Z/P1D), window_start/window_end bounds, and max_occurrences caps (default 100, max 10,000) with explicit truncated reporting.
Bulk stats example — hand it your entire event log; the response stays tiny no matter how many timestamps go in (up to 100,000):
Every tool response includes a second content block — a single ~20-token line giving the calling agent passive time-awareness:
text
⏱ now 2026-08-09T15:02:11.123-04:00 (Sun) · first call this session
⏱ now 2026-08-09T15:49:03.456-04:00 (Sun) · +46m52s since last call · session 47m1s · call #2
LLMs have no innate sense of elapsed time between turns; the envelope makes time passage visible on every interaction with the server — including the weekday, which models frequently miscompute. Disable it by setting CHRONO_ENVELOPE=off in the server environment.
Development
Prerequisites
Node.js >= 22.0.0
npm or yarn
Setup
bash
git clone https://github.com/yourusername/chrono-mcp.git
cd chrono-mcp
npm install
Build
bash
npm run build
Testing & Inspector
bash
npm test
npm run test:ui
npm run test:mcp
npm run inspector
bash
npm run bench
npm test — Vitest unit tests for tool handlers
npm run bench — Vitest benchmarks proving every batch operation at the MAX_OPERATIONS cap (10,000 items) completes in well under 100ms
npm run test:mcp — Vibrissa (npm: @jmoak/vibrissa) MCP protocol cases (requires npm run build first; no Python)
Protocol contracts live in tests/contracts/*.tdd and emit to tests/integration/vibrissa/cases/ via tdd-dsl locally (npm run contracts:emit if tdd-dsl is on your PATH). CI runs only the committed JSON with vib run.
Visit http://localhost:6274 for the web inspector UI.
Linting
bash
npm run lint
npm run lint:fix
Supported Timezones
Supports all IANA timezone identifiers including:
Americas: America/New_York, America/Los_Angeles, America/Toronto, etc.
Europe: Europe/London, Europe/Paris, Europe/Berlin, etc.
Asia: Asia/Tokyo, Asia/Shanghai, Asia/Dubai, etc.
Australia: Australia/Sydney, Australia/Melbourne, etc.
And 400+ more...
Acknowledgments
This project is powered by Luxon, the excellent DateTime library that provides robust timezone handling and date arithmetic. We're grateful to the Luxon team for creating such a reliable foundation for temporal operations.