Epoch Calculator MCP server

Time and date math that language models get wrong on their own: Unix timestamps, daylight-saving offsets, calendar arithmetic, and cron schedules. Every calculation uses the IANA time zone database, the same engine behind epochcalc.com.

No API key, no signup, no state. All tools are read-only.

Connect

The server is hosted at https://epochcalc.com/mcp (Streamable HTTP, stateless). Point any MCP client at it directly:

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

{
  "mcpServers": {
    "epochcalc": { "type": "http", "url": "https://epochcalc.com/mcp" }
  }
}

stdio clients

For clients that only speak stdio, this package is a zero-dependency bridge to the hosted server (Node 18+):

{
  "mcpServers": {
    "epochcalc": { "command": "npx", "args": ["-y", "@cmunkres/epochcalc-mcp"] }
  }
}

Or with Docker:

docker build -t epochcalc-mcp .
docker run -i --rm epochcalc-mcp

Set EPOCHCALC_MCP_URL to point the bridge at a different endpoint.

Tools

| Tool | What it does | |---|---| | time_now | Current time in any zone, with epoch seconds, ISO 8601, RFC 2822, and DST flag | | convert_timestamp | Unix timestamp (seconds or milliseconds, auto-detected) to a full date breakdown | | parse_datetime | Natural or ISO date string to timestamp and zone-aware fields | | convert_timezone | Same instant in two zones, with the hour difference and DST status of each | | date_duration | Days, weekdays, weeks, and calendar breakdown between two dates | | epoch_math | Add or subtract years, months, weeks, days, hours, minutes, or seconds | | cron_next_runs | Plain-English explanation of a cron expression plus its next N run times | | days_until | Countdown to a named holiday or event, or list the supported events |

Every tool declares readOnlyHint, an input schema, and an output schema. The full machine-readable index is at epochcalc.com/api/v1.

Example prompts

• "What time is it in Tokyo right now, and is it on daylight saving?"
• "Convert 1700000000 to a readable date in London time."
• "When are the next three runs of 0 9 * * 1-5 in New York?"
• "How many weekdays are between 2026-02-28 and 2026-04-01?"

Notes

• Time zones are IANA names such as America/New_York or Europe/Berlin. Abbreviations like EST are ambiguous and rejected.
• The same tools are available as a plain JSON API at https://epochcalc.com/api/v1 (GET with query parameters or POST with a JSON body).
• Documentation: epochcalc.com/api

Test

npm test

Runs initialize, tools/list, and one tools/call through the bridge against the live server.

License

MIT