chrono-mcp

A comprehensive Model Context Protocol (MCP) server providing advanced date, time, timezone, and calendar operations powered by Luxon. Perfect for AI agents and applications that need robust temporal data handling.

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)

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"
    }
  }
}

Features

• Global Timezone Support - Work with all IANA timezone identifiers
• Time Calculations - Add/subtract durations, calculate differences between dates
• Multiple Formats - ISO, RFC2822, SQL, locale-aware, and custom formatting
• Type Safety - Zod validation with comprehensive error handling
• Real-time - Current time retrieval with microsecond precision
• Easy Integration - Standard MCP protocol for seamless AI agent integration
• Token-Optimized Output - Dynamically shaped responses that maximize information density while minimizing token usage for efficient AI interactions

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 operations including duration calculations and date math.

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
• sort - Sort timestamps chronologically

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"
}

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 test — Vitest unit tests for tool handlers
• npm run test:mcp — 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.