Content
# MCP Clock
**Live MCP endpoint:** `https://mcpclock.firasd.workers.dev/mcp`
Works in Claude.ai, Claude iOS, Claude Code, OpenAI Codex, and any MCP-compatible client.
---
## Tools
### `clock_get`
Returns current time in one or more time zones.
- **`timezones`** *(optional)* — Array of IANA zone names (e.g. `"America/New_York"`) plus the special literals `"UTC"` and `"Alphadec"`. Defaults to `["UTC"]`. Max 15 zones.
- **`offsetSeconds`** *(optional)* — Signed offset in seconds applied before formatting. E.g. `-86400` for 24 h ago, `+60` for one minute ahead.
- **`adec_canonical_only`** *(optional)* — Pass `"true"` to suppress the Alphadec unit explanation and return only the canonical string.
```json
clock_get{}
clock_get{"timezones": ["Asia/Tokyo", "America/New_York"]}
clock_get{"timezones": ["Alphadec"], "adec_canonical_only": "true"}
```
---
### `clock_day_info`
Returns calendar information for a UTC date — weekday, days in month, day of year, days in year, year progress %, ISO week number, and the corresponding Hijri (Islamic) date.
- **`date`** *(optional)* — Date in `YYYY-MM-DD` format. Defaults to today (UTC).
The `hijri_calendar` field returns two variants: `tabular` (`islamic-tbla`, the arithmetic/tabular calendar) and `umm_al_qura` (`islamic-umalqura`, the Saudi civil calendar).
```json
clock_day_info{}
clock_day_info{"date": "2025-09-09"}
```
---
### `clock_convert`
Converts a timestamp from one time zone to one or more target zones.
- **`source_zone`** — IANA zone name or `"UTC"`.
- **`iso`** — ISO-8601 string. If source is `"UTC"`, include the `Z` suffix. If source is an IANA zone, omit the offset (wall-clock time).
- **`target_zones`** — Array of IANA zone names or `"UTC"`. Min 1, max 15.
```json
clock_convert{
"source_zone": "America/Mexico_City",
"iso": "2025-10-28T07:30:00",
"target_zones": ["UTC", "Asia/Dubai"]
}
```
---
### `clock_convert_alphadec`
Converts between a UTC ISO timestamp and an Alphadec string.
- **`direction`** — `"utc_to_alphadec"` (default) or `"alphadec_to_utc"`.
- **`value`** — UTC ISO string (e.g. `"2025-06-09T16:30:00.000Z"`) or Alphadec string (e.g. `"2025_L3T5_000000"`).
```json
clock_convert_alphadec{"direction": "utc_to_alphadec", "value": "2025-06-09T16:30:00.000Z"}
clock_convert_alphadec{"direction": "alphadec_to_utc", "value": "2025_L3T5_000000"}
```
---
### `clock_convert_unixtime`
Converts between a UTC ISO timestamp and a Unix timestamp (seconds since epoch).
- **`direction`** — `"utc_to_unixtime"` (default) or `"unixtime_to_utc"`.
- **`value`** — UTC ISO string (e.g. `"2025-06-15T12:00:00Z"`) or Unix timestamp string (e.g. `"1749988800"`).
```json
clock_convert_unixtime{"direction": "utc_to_unixtime", "value": "2025-06-15T12:00:00Z"}
clock_convert_unixtime{"direction": "unixtime_to_utc", "value": "1749988800"}
```
---
### `clock_shift_utc`
Shifts a UTC ISO timestamp forward or backward by a structured time delta ("what date is 35 days from now?").
- **`date_from`** — Required. Either the literal string `"NOW"` (current UTC instant) or a UTC ISO timestamp like `"2026-05-28T10:00:00Z"`.
- **`direction`** *(optional)* — `"after"` (default) or `"before"`.
- **`delta`** *(optional)* — Object with non-negative integer fields: `years`, `days`, `hours`, `minutes`, `seconds`. Missing fields default to zero.
Years move on the UTC calendar (so Feb 29 → Feb 28/Mar 1 behaviour follows the calendar), then days/hours/minutes/seconds are applied on the UTC timeline. Returns `source_utc_iso`, `shifted_utc_iso`, the `input_delta`, a `normalized_delta`, and `total_seconds_excluding_calendar_years`.
```json
clock_shift_utc{"date_from": "NOW", "delta": {"days": 35}}
clock_shift_utc{"date_from": "2026-02-28T12:00:00Z", "direction": "after", "delta": {"years": 1}}
clock_shift_utc{"date_from": "2026-05-28T10:00:00Z", "direction": "before", "delta": {"seconds": 3600}}
```
---
### `clock_delta_utc`
Calculates the time difference between two UTC ISO timestamps. Omit either end to use the current time (i.e. "time since" or "time until").
- **`start`** *(optional)* — UTC ISO timestamp (e.g. `"2022-01-15T10:30:00Z"`). Defaults to now.
- **`end`** *(optional)* — UTC ISO timestamp. Defaults to now. At least one of `start` or `end` is required.
Returns `total_seconds`, a `breakdown` (years/days/hours/minutes/seconds), and a `readable` string. Negative if start is after end.
```json
clock_delta_utc{"start": "2022-01-15T10:30:00Z"}
clock_delta_utc{"end": "2025-12-31T23:59:59Z"}
clock_delta_utc{"start": "2022-01-15T10:30:00Z", "end": "2025-08-31T14:45:30Z"}
```
---
### `clock_delta_alphadec`
Calculates the time difference between two 4-character Alphadec codes within the current year. Omit either end to use the current time.
- **`alphadec_start`** *(optional)* — 4-character Alphadec code (e.g. `"A2B3"`). Defaults to now.
- **`alphadec_end`** *(optional)* — 4-character Alphadec code (e.g. `"Z8Y9"`). Defaults to now. At least one is required.
Returns both ISO time difference and Alphadec unit delta (periods/arcs/bars/beats).
```json
clock_delta_alphadec{"alphadec_start": "A2B3"}
clock_delta_alphadec{"alphadec_end": "Z8Y9"}
clock_delta_alphadec{"alphadec_start": "A2B3", "alphadec_end": "C1Y9"}
```
---
## CLI usage
The endpoint is plain streamable-HTTP JSON-RPC, so `curl` works fine. Send `Accept: application/json, text/event-stream` — responses come back as SSE frames.
**List the available tools:**
```bash
curl -s -X POST "https://mcpclock.firasd.workers.dev/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
| grep '^data:' | sed 's/^data: //' | jq -r '.result.tools[].name'
```
```
clock_get
clock_day_info
clock_convert
clock_convert_alphadec
clock_convert_unixtime
clock_shift_utc
clock_delta_utc
clock_delta_alphadec
```
**Call a tool:**
```bash
curl -s -X POST "https://mcpclock.firasd.workers.dev/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"clock_get","arguments":{}}}'
```
```
event: message
data: {"result":{"content":[{"type":"text","text":"[\n {\n \"timezone\": \"UTC\",\n \"iso\": \"2026-08-05T08:31:36.657Z\",\n \"unixtime\": 1785918696\n },\n {\n \"timezone\": \"Alphadec\",\n \"alphadec\": \"2026_P4D0_086006\"\n }\n]"}]},"jsonrpc":"2.0","id":1}
```
**Pretty-print just the tool's text payload:**
```bash
curl -s -X POST "https://mcpclock.firasd.workers.dev/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"clock_shift_utc","arguments":{"date_from":"NOW","delta":{"days":35}}}}' \
| grep '^data:' | sed 's/^data: //' | jq -r '.result.content[0].text'
```
---
## Alphadec
Alphadec is a compact, human-readable timestamp format. A full canonical string looks like `2026_I2J9_382995`.
| Unit | Characters | Approx. Duration |
|------|-----------|-----------------|
| Period | A–Z (1st char) | ~14.04 days (year ÷ 26) |
| Arc | 0–9 (2nd char) | ~33.7 hours (period ÷ 10) |
| Bar | A–Z (3rd char) | ~77.75 minutes (arc ÷ 26) |
| Beat | 0–9 (4th char) | ~7.78 minutes (bar ÷ 10) |
| Offset | 6-digit suffix | milliseconds within beat |
Alphadec strings are K-sortable — lexicographic order matches chronological order. Truncating to fewer characters creates natural time groupings (e.g. `2026_I2` covers the entire I2 arc).
Seasonal anchors (approximate): Period F = March equinox · Period M = June solstice · Period S = September equinox · Period Z = December solstice.
---
## License
[The Unlicense](https://unlicense.org/) — this is free and unencumbered software released into the public domain. Do whatever you want with it.
