Skip to main content
Glama
JMoak

Chrono MCP

by JMoak
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

chrono-mcp

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.

NPM Version Downloads Node Version License: MIT TypeScript Code Style: Biome Tests: Vitest MCP Server Powered by Luxon

Quick Start

npx @jmoak/chrono-mcp

Run as local HTTP server

npm install
npm run build
npm run start:http
# Server listens on http://localhost:8000/mcp (health check at /health)

Related MCP server: Date MCP Server

MCP Client Configuration

Configure your MCP client to launch chrono-mcp via npx. Below are client-specific examples.

Claude Code

Ask Claude! Here's the configuration:

{
  "mcpServers": {
    "chrono-mcp": {
      "command": "npx",
      "args": ["-y", "@jmoak/chrono-mcp@latest"]
    }
  }
}

Cursor

Reference: Cursor MCP docs

{
  "mcpServers": {
    "chrono-mcp": {
      "command": "npx",
      "args": ["-y", "@jmoak/chrono-mcp@latest"]
    },
    "chrono-mcp-http": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Why chrono-mcp

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

  • Examples - Practical usage examples and patterns

Available Tools

GET TIME

Get current time or convert times across timezones with flexible formatting.

Parameters:

  • datetime (string, optional): ISO datetime string. Defaults to current time

  • timezones (array, optional): List of timezone names for conversions

  • formats (array, optional): Output formats (iso, rfc2822, sql, local, localeString, short, medium, long, full)

  • locale (string, optional): Locale for formatting (e.g., en-US, fr-FR, ja-JP)

  • includeOffsets (boolean, optional): Include UTC offsets in output

Example:

Input

{
  "datetime": "2024-01-01T12:00:00Z",
  "timezones": ["America/New_York", "Asia/Tokyo"],
  "includeOffsets": true
}

Output

{
  "baseTime": "2024-01-01T12:00:00.000Z",
  "America/New_York": "2024-01-01T07:00:00.000-05:00",
  "Asia/Tokyo": "2024-01-01T21:00:00.000+09:00"
}

TIME CALCULATOR

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.

Expand example:

Input

{
  "operation": "expand",
  "recurrence": "FREQ=WEEKLY;BYDAY=TU;COUNT=4",
  "base_time": "2026-02-24T09:00:00[America/New_York]",
  "occurrence_format": "ixdtf"
}

Output (result excerpt — note the wall-clock time held across the DST transition)

{
  "rule_type": "rrule",
  "count": 4,
  "truncated": false,
  "occurrences": [
    "2026-02-24T09:00:00.000-05:00[America/New_York]",
    "2026-03-03T09:00:00.000-05:00[America/New_York]",
    "2026-03-10T09:00:00.000-04:00[America/New_York]",
    "2026-03-17T09:00:00.000-04:00[America/New_York]"
  ]
}

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):

{
  "operation": "stats",
  "base_time": ["2026-01-01T00:00:00Z", "...99,998 more...", "2026-01-02T03:46:39Z"]
}

Output (aggregates only — real excerpt from a 100,000-timestamp call that ran in ~500ms)

{
  "input_analysis": { "base_time_count": 100000 },
  "timestamp_analysis": {
    "earliest": "2026-01-01T00:00:00.000Z",
    "latest": "2026-01-02T03:46:39.000Z",
    "total_span_human": "1 day, 3 hours, 46 minutes, 39 seconds",
    "std_deviation_ms": 28867513
  },
  "interval_analysis": {
    "interval_count": 99999,
    "mean_interval_human": "1 second"
  }
}

Parameters:

  • operation (required): Type of calculation

  • interaction_mode (optional): auto_detect | single_to_many | many_to_single | pairwise | cross_product | aggregate. Defaults to auto_detect.

  • base_time (optional): Base ISO datetime(s). String or array. Defaults to current time.

  • compare_time (optional): Compare ISO datetime(s) for diff/duration_between. String or array.

  • timezone (optional): Timezone for base_time

  • compare_time_timezone (optional): Timezone for compare_time

  • years, months, days, hours, minutes, seconds (optional): Duration values

Example:

Input

{
  "operation": "add",
  "base_time": "2024-12-25T10:00:00Z",
  "days": 5,
  "hours": 3
}

Output

{
  "operation": "add",
  "interaction_mode": "single_to_single",
  "input": {
    "base_time": "2024-12-25T10:00:00.000Z",
    "duration": { "days": 5, "hours": 3 }
  },
  "result": "2024-12-30T13:00:00.000Z",
  "result_timezone": "UTC"
}

Temporal Context Envelope

Every tool response includes a second content block — a single ~20-token line giving the calling agent passive time-awareness:

⏱ 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.

Prerequisites

  • Node.js >= 22.0.0

  • npm or yarn

Setup

git clone https://github.com/yourusername/chrono-mcp.git
cd chrono-mcp
npm install

Build

npm run build

Testing & Inspector

npm test
npm run test:ui
npm run test:mcp
npm run inspector
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

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.

License

MIT License - see the LICENSE file for details.

Releases

See GitHub Releases for detailed changes.

Available Tools

2 tools
GET TIMEAInspect

Get current time or convert times across timezones with flexible formatting. Defaults to current time in system timezone when no parameters provided. Use timezones array to get multiple zones, formats array for multiple output formats.

ParametersJSON Schema
NameRequiredDescriptionDefault
datetimeNoOptional. ISO datetime string (e.g., '2024-12-25T15:00:00'). If not provided, current time is used.
timezonesNoList of timezone names to include in output. Examples: ['America/New_York', 'Asia/Tokyo', 'Europe/London']
formatsNoOutput formats for the base datetime only (not applied to individual timezones). Creates separate entries for each format.
localeNoLocale for formatting (e.g., 'en-US', 'fr-FR', 'ja-JP'). Affects localeString and relative formats.
includeOffsetsNoInclude UTC offsets like +09:00, -04:00 in output

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the default behavior and some operational details (multiple timezones/formats handling), but doesn't cover important aspects like error handling, rate limits, authentication requirements, or what the output structure looks like. The description adds some value but leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with three sentences that each serve a distinct purpose: stating the core functionality, describing default behavior, and explaining array parameter usage. There's no wasted verbiage and information is front-loaded appropriately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (5 parameters, timezone/formats logic) and lack of both annotations and output schema, the description is incomplete. While it covers basic usage, it doesn't explain the output format, error conditions, or provide examples of what the tool returns. The description should do more to compensate for the missing structured information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds minimal value beyond what's in the schema - it mentions the timezones and formats arrays but doesn't provide additional semantic context. This meets the baseline expectation when schema coverage is complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('get current time' and 'convert times across timezones') and resources (time with formatting). It distinguishes from the sibling 'TIME CALCULATOR' by focusing on retrieval/conversion rather than calculation operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool ('Defaults to current time in system timezone when no parameters provided') and mentions usage patterns ('Use timezones array to get multiple zones, formats array for multiple output formats'). However, it doesn't explicitly state when NOT to use it or mention the sibling tool as an alternative for calculation tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TIME CALCULATORBInspect

Perform time arithmetic operations including duration calculations, date math, interval operations, statistical analysis, and sorting. Use for adding/subtracting time periods, calculating differences between dates, analyzing time-based datasets, or sorting arrays of timestamps.

ParametersJSON Schema
NameRequiredDescriptionDefault
operationYesType of calculation to perform
interaction_modeNoHow base_time and compare_time arrays interact. 'auto_detect' handles single-to-single, single-to-many, many-to-single automatically. Defaults to 'auto_detect'
base_timeNoBase ISO datetime(s). Single string or array. Defaults to current time if not provided
compare_timeNoCompare ISO datetime(s) for diff/duration_between operations. Single string or array
timezoneNoTimezone for base_time (e.g., 'America/New_York')
compare_time_timezoneNoTimezone for compare_time. If not provided, base_time timezone is used
yearsNoYears to add/subtract
monthsNoMonths to add/subtract
daysNoDays to add/subtract
hoursNoHours to add/subtract
minutesNoMinutes to add/subtract
secondsNoSeconds to add/subtract

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions the types of operations, it doesn't disclose important behavioral traits like whether operations are read-only or mutating, error handling for invalid inputs, performance characteristics, or what the return values look like. For a complex tool with 12 parameters, this is a significant gap in behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with two sentences that efficiently cover purpose and usage. The first sentence establishes the scope of operations, and the second provides specific use cases. There's no wasted text, and information is front-loaded, though it could be slightly more structured by grouping related operations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 12 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't address what the tool returns, how errors are handled, performance considerations, or provide guidance on parameter combinations for different operations. The schema covers parameter definitions well, but the description fails to provide the contextual understanding needed for effective tool use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no specific parameter semantics beyond what's in the schema - it doesn't explain how parameters interact, which parameters are required for which operations, or provide additional context about parameter usage. Baseline 3 is appropriate when the schema does all the parameter documentation work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs 'time arithmetic operations' and lists specific functions like duration calculations, date math, and sorting. It distinguishes from the sibling 'GET TIME' by emphasizing calculations rather than retrieval, though it doesn't explicitly contrast them. The verb+resource combination is specific but could be more precise about the computational nature.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage contexts with 'Use for adding/subtracting time periods, calculating differences between dates, analyzing time-based datasets, or sorting arrays of timestamps.' This gives explicit when-to-use guidance for different scenarios. However, it doesn't mention when NOT to use it or explicitly compare with the sibling 'GET TIME' tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv1.0.0
    • First observedGET TIME
    • First observedTIME CALCULATOR
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: GET TIME focuses on time retrieval, conversion, and formatting, while TIME CALCULATOR handles arithmetic operations, duration calculations, and data analysis. There is no overlap in functionality, making it easy for an agent to choose the correct tool based on the task.

Naming Consistency3/5

The naming is mixed: GET TIME uses uppercase with a space, while TIME CALCULATOR uses uppercase with a space but includes a more descriptive term. This inconsistency in style (e.g., no uniform verb_noun pattern) reduces predictability, though the names remain readable and descriptive of their functions.

Tool Count3/5

With only 2 tools, the server feels thin for a time-related domain that could benefit from more operations like scheduling, timezone management, or recurring events. While the tools cover basic needs, the count is borderline low for comprehensive time handling, suggesting potential under-scoping.

Completeness3/5

The tools cover core time operations (retrieval/conversion and arithmetic/analysis), but there are notable gaps such as scheduling, timezone database updates, or handling recurring events. Agents can work around these with the provided tools, but the surface is not fully complete for advanced time management tasks.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Time MCP Server

    ampcome-mcps
    A
    license
    B
    quality
    D
    maintenance
    Gives large language models time awareness capabilities through various time-related functions including current time retrieval, timezone conversion, and relative time calculations.
    6
    1,823
    MIT

  • Date MCP Server

    ainarsklavins
    A
    license
    A
    quality
    Not graded
    maintenance
    Provides AI assistants with real-time date, time, and timezone information, enabling them to access current temporal data, format dates, calculate day of week, and work with different timezones.
    4
    7
    -

  • Date-time Tools MCP

    abhi12299
    A
    license
    A
    quality
    D
    maintenance
    Provides tools for date-time manipulation, including timezone conversion and arithmetic operations like adding or subtracting time units. It also enables users to retrieve current date, time, and timezone information.
    3
    43
    ISC

  • mcp-time-tools

    rog0x
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides date, time, and timezone tools for AI agents via MCP, including timezone conversion, date calculation, cron parsing, timestamp conversion, and duration formatting.
    54
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/JMoak/chrono-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server