# 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](https://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:

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

```json
{
  "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+):

```json
{
  "mcpServers": {
    "epochcalc": { "command": "npx", "args": ["-y", "epochcalc-mcp"] }
  }
}
```

Or with Docker:

```bash
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](https://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](https://epochcalc.com/api)

## Test

```bash
npm test
```

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

## License

MIT