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](https://docs.cursor.com/context/model-context-protocol# configuring-mcp-servers)

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

# 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 inspector

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.