Date Difference Calculator MCP Server

A Model Context Protocol (MCP) server for calculating the difference between two dates/times, returning the duration in years, months, days, hours, minutes, and seconds — plus total days, hours, minutes, and seconds. Perfect for utility tooling, time span queries, contest timers, or productivity use.

Features

• calculate_date_difference: Computes precise time spans between any two dates/times in ISO 8601 format.
• Returns both a breakdown by years, months, days, etc., and total units.
• Robust error handling and production-grade edge case management.

Installation

The easiest way is via npx (no install needed):

npx @dennisk2025/date-difference-calculator

Or, install system-wide or locally:

npm install -g @dennisk2025/date-difference-calculator

Using with Claude Desktop

Add the following snippet to your Claude Desktop config file:

{
  "mcpServers": {
    "date-diff": {
      "command": "npx",
      "args": ["@dennisk2025/date-difference-calculator"]
    }
  }
}

Add this to your Claude Desktop config file at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Available Tools

1. calculate_date_difference

Description: Given two dates in ISO 8601 format, computes the duration in years, months, days, hours, minutes, seconds, and as total days/hours/minutes/etc.

Parameters:

• start_date (string, ISO 8601, required): The start date (e.g., 2023-06-15T12:00:00Z)
• end_date (string, ISO 8601, required): The end date (e.g., 2024-01-01T00:00:00Z)

Returns:

{
  "start_date": "...",
  "end_date": "...",
  "swap": false,  // true if "start date" and "end date" were reversed chronologically
  "duration": {
    "years": 0,
    "months": 6,
    "days": 16,
    "hours": 12,
    "minutes": 0,
    "seconds": 0
  },
  "total": {
    "milliseconds": 123456789,
    "seconds": 123456,
    "minutes": 2057,
    "hours": 34,
    "days": 1
  }
}

Example Usage

Minimal:

{"start_date": "2023-06-15T12:00:00Z", "end_date": "2024-01-01T00:00:00Z"}

Swapped (handles automatically):

{"start_date": "2024-01-01T00:00:00Z", "end_date": "2023-06-15T12:00:00Z"}

Millisecond resolution and leap years supported!

Troubleshooting

• Dates must be valid ISO-8601 strings (with or without timezone, but UTC preferred, i.e., ending in Z).
• If the start_date is after end_date, the output will be identical with the swap field noted.
• All calculations are in UTC — for local time, please convert before sending to this server.

License

MIT

Enjoy precision date difference calculations in any Model Context Protocol–enabled tool!