# clock-mcp

A one-tool MCP server that tells the model what day and time it is.

## Why

Language models have no clock. Asked for today's date, a model with tools will
reach for whatever search tool is in reach — a billed API call and a network
round trip to learn something the machine it is running on already knows, and
often an answer scraped off a page that is itself stale.

This is the cheap answer: read the system clock, return it. No network, no API
key, no state on disk.

## The tool

`get_current_time(timezone_name: str | None = None)`

`timezone_name` takes an IANA name (`America/Denver`, `Asia/Tokyo`) or `UTC`.
Omit it for the host's local zone. An unknown name raises an error rather than
silently falling back to UTC — a wrong timezone is worse than a refusal.

```json
{
  "iso8601": "2026-09-13T14:05:09-06:00",
  "date": "2026-09-13",
  "time": "14:05:09",
  "day_of_week": "Sunday",
  "timezone": "America/Denver",
  "timezone_abbreviation": "MDT",
  "utc_offset": "-06:00",
  "utc_iso8601": "2026-09-13T20:05:09+00:00",
  "unix_timestamp": 1789243509,
  "human": "Sunday, September 13, 2026 at 2:05 PM MDT"
}
```

Both a machine half and a human half, because callers want different ones:
`date` and `unix_timestamp` for arithmetic, `human` for dropping straight into
a reply.

## Install

```bash
git clone https://github.com/garland3/clock-mcp.git
cd clock-mcp
uv venv && uv pip install -e '.[dev]'

.venv/bin/clock-mcp --list-tools     # get_current_time
.venv/bin/python -m pytest -q
```

## Register it

Claude Code:

```bash
claude mcp add clock -- /path/to/clock-mcp/.venv/bin/clock-mcp --stdio
```

Anything that reads a JSON MCP config:

```json
{
  "clock": {
    "command": ["/path/to/clock-mcp/.venv/bin/clock-mcp", "--stdio"],
    "transport": "stdio"
  }
}
```

## One implementation note

The default zone is resolved from `$TZ` or the `/etc/localtime` symlink, not
from `datetime.now().astimezone()`. That call only ever yields a *fixed offset*
named for the current abbreviation (`MDT`), which throws away both the zone name
and its DST rules — so the tool would report `MDT` where you want
`America/Denver`. `tzdata` is a dependency so named zones resolve even on a host
with no system zoneinfo tree.

## License

MIT