Epoch Calculator API and MCP server

Connect an AI assistant (MCP)

Endpoint: https://epochcalc.com/mcp (Streamable HTTP, stateless, no auth). Language models are unreliable at date arithmetic and daylight-saving offsets; giving them these tools fixes that.

# Claude Code
claude mcp add --transport http epochcalc https://epochcalc.com/mcp

# Claude Desktop / Cursor / any MCP client (config JSON)
{
  "mcpServers": {
    "epochcalc": { "type": "http", "url": "https://epochcalc.com/mcp" }
  }
}

Call it directly (JSON API)

Base URL https://epochcalc.com/api/v1. Every tool accepts GET with query parameters or POST with a JSON body, and returns { tool, result }. Nested arguments use dotted keys in query strings. Errors come back as HTTP 400 with a message.

curl "https://epochcalc.com/api/v1/convert_timestamp?timestamp=1700000000&timezone=Europe/London"

curl "https://epochcalc.com/api/v1/cron_next_runs?expression=0+9+*+*+1-5&timezone=America/New_York&count=3"

curl -X POST https://epochcalc.com/api/v1/convert_timezone \
  -H "content-type: application/json" \
  -d '{"datetime":"2026-03-08T01:30","from_timezone":"America/New_York","to_timezone":"Asia/Tokyo"}'

curl "https://epochcalc.com/api/v1/epoch_math?add.days=30&timezone=UTC"

Tools

The full machine-readable index, including JSON Schemas, is at /api/v1.

time_nowtimezone

The current time: Unix epoch in seconds and milliseconds, ISO 8601, and the local wall-clock time in a given IANA time zone with its current UTC offset and DST status. Use this before any relative date reasoning.

convert_timestamptimestamp, unit, timezone

Convert a Unix timestamp (seconds or milliseconds; auto-detected unless unit is given) to a human-readable date in a time zone, with ISO 8601, RFC 2822, UTC offset, DST flag, weekday, and a relative phrase like "3 days ago".

parse_datetimeinput, timezone

Parse a date/time string (ISO 8601, RFC 2822, HTTP date, SQL "YYYY-MM-DD HH:mm:ss", or a Unix timestamp) into a Unix timestamp and a normalized description. Strings without an offset are interpreted in the given time zone.

convert_timezonedatetime, from_timezone, to_timezone

Convert a wall-clock date/time from one IANA time zone to another, correctly across daylight-saving transitions. Returns both sides with offsets, the hour difference at that instant, and whether either zone is on DST.

date_durationstart, end, timezone, include_end

The exact duration between two dates or date-times: calendar years/months/days, plus total days, hours, minutes and seconds, and the number of weekdays (Mon-Fri). Handles leap years and DST via the IANA database.

epoch_mathtimestamp, add, subtract, timezone

Add to or subtract from a Unix timestamp in calendar-aware units (years, months, weeks, days, hours, minutes, seconds) in a time zone, e.g. "now + 30 days" or "1748736543 - 3 months". Returns the resulting timestamp in every format.

cron_next_runsexpression, timezone, count, from

Explain a 5- or 6-field cron expression in plain English and list its next run times in a time zone (as ISO 8601 and Unix timestamps). Use to answer "when does this cron job run next?" or to validate an expression.

days_untilevent, date, timezone

Countdown to a holiday or to a date: days, hours and minutes remaining, and the next occurrence date. Pass an event slug (e.g. "christmas", "thanksgiving", "easter", "super-bowl") or a date (YYYY-MM-DD). Call with no arguments to list the known events.

Example response

GET /api/v1/convert_timezone?datetime=2026-07-01T09:00&from_timezone=Asia/Tokyo&to_timezone=Europe/London

{
  "tool": "convert_timezone",
  "result": {
    "source": { "iso": "2026-07-01T09:00:00.000+09:00", "abbreviation": "GMT+9", "is_dst": false, ... },
    "target": { "iso": "2026-07-01T01:00:00.000+01:00", "abbreviation": "BST",   "is_dst": true,  ... },
    "difference_hours": -8,
    "same_instant_utc": "2026-07-01T00:00:00.000Z"
  }
}

Frequently asked questions

Do I need an API key?

No. Every endpoint is public, read-only, and free. Please cache responses that do not depend on the current time, and keep automated traffic reasonable.

What is the MCP endpoint for?

Model Context Protocol lets AI assistants such as Claude, ChatGPT, or Cursor call these tools directly, so an agent gets correct DST-aware time math instead of estimating it. Point an MCP client at https://epochcalc.com/mcp.

Which time zones are supported?

Any IANA zone name, for example America/New_York, Europe/Berlin, or Asia/Kolkata. Abbreviations like EST are ambiguous and are not accepted.

Is the data accurate across daylight saving changes?

Yes. All calculations use the IANA time zone database via Luxon, the same engine as the tools on this site, so transitions, historical offsets, and leap years are handled correctly.