timestamp_convert MCP tool: Unix time and dates for AI agents

Timestamps trip up language models in three ways. The arithmetic is error-prone: turning 1767229200 into a date is a division and a calendar calculation with leap years, done in the model’s head. Time zones need a rule database the model only half remembers, including the date daylight saving time started in a given country and year. And a model doesn’t know what time it is now, so “how long ago was this?” gets an answer relative to whenever its training data ended.

The devtoolbox.cc MCP server includes timestamp_convert, which hands those calculations to code. It runs the same logic as the Unix timestamp converter on this site and reads the computer’s clock for “now”. Setup instructions are on the MCP page.

What the tool does

There are three ways to call it:

• With a timestamp: the number of seconds, milliseconds, microseconds or nanoseconds since 1970. The unit is detected from the size of the number (10 digits are seconds, 13 milliseconds, and so on) unless you set it.
• With a date: an ISO 8601 date or date-time. With Z or an offset like +02:00 it’s an exact instant. Without one, it’s read as a local time in time_zone.
• With neither: the current time.

Every answer contains the same fields: seconds, milliseconds, ISO 8601 in UTC, RFC 2822, the local time and UTC offset in the chosen zone, and a relative description such as “3 hours ago”.

Impossible dates are rejected instead of rolled over: February 30 is an error, not March 1. Local times that don’t exist because the clocks jumped forward are rejected too. Local times that happen twice, when the clocks go back, use the first occurrence and say so.

Arguments

Argument	Type	Meaning
timestamp	string	A Unix timestamp, e.g. "1700000000" or "1700000000000".
unit	"s", "ms", "us", "ns"	Unit of timestamp. Detected if omitted.
date	string	An ISO 8601 date, e.g. "2026-05-01T12:00:00Z".
time_zone	string	An IANA zone such as "Europe/Berlin". Default "UTC".

Examples

These examples were run against the real tool with the clock set to 2026-10-24 12:00 UTC, which is why the relative times are counted from that moment. A timestamp in milliseconds, shown in Berlin time:

{ "timestamp": "1767229200000", "time_zone": "Europe/Berlin" }

Unit: milliseconds (detected)
Seconds: 1767229200
Milliseconds: 1767229200000
ISO 8601: 2026-01-01T01:00:00.000Z
RFC 2822: Thu, 01 Jan 2026 01:00:00 +0000
Europe/Berlin (+01:00): 2026-01-01 02:00:00
Relative: 10 months ago

The 13 digits were recognised as milliseconds. The same number read as seconds by mistake is a classic bug, and the tool’s output makes it obvious, because the result lands about 56,000 years in the future:

{ "timestamp": "1767229200000", "unit": "s" }

Unit: seconds
Seconds: 1767229200000
Milliseconds: 1767229200000000
ISO 8601: +057971-04-07T16:00:00.000Z
RFC 2822: Wed, 07 Apr 57971 16:00:00 +0000
UTC (+00:00): 57971-04-07 16:00:00
Relative: in 55,982 years

The other direction, a meeting time in New York to a timestamp:

{ "date": "2026-11-02T09:30:00", "time_zone": "America/New_York" }

Seconds: 1793629800
Milliseconds: 1793629800000
ISO 8601: 2026-11-02T14:30:00.000Z
RFC 2822: Mon, 02 Nov 2026 14:30:00 +0000
America/New_York (-05:00): 2026-11-02 09:30:00
Relative: in 9 days

On 2026-03-08 the clocks in New York jumped from 02:00 to 03:00, so 02:30 that night never happened. The tool refuses it rather than silently shifting it by an hour:

{ "date": "2026-03-08T02:30:00", "time_zone": "America/New_York" }

2026-03-08 02:30:00 doesn't exist in America/New_York: the clocks skip it for daylight saving time (UTC-05:00 → UTC-04:00). Add an offset such as -05:00 to mean a specific instant.

On 2026-11-01 the clocks go back, and 01:30 happens twice. The tool uses the first occurrence and gives the timestamp of the second in a note:

{ "date": "2026-11-01T01:30:00", "time_zone": "America/New_York" }

Note: 2026-11-01 01:30:00 happens twice in America/New_York (the clocks go back). Using the first occurrence, UTC-04:00; the second, UTC-05:00, is 1793514600.
Seconds: 1793511000
Milliseconds: 1793511000000
ISO 8601: 2026-11-01T05:30:00.000Z
RFC 2822: Sun, 01 Nov 2026 05:30:00 +0000
America/New_York (-04:00): 2026-11-01 01:30:00
Relative: in 8 days

And with no arguments, the current time, here the fixed clock of the examples:

{}

Seconds: 1792843200
Milliseconds: 1792843200000
ISO 8601: 2026-10-24T12:00:00.000Z
RFC 2822: Sat, 24 Oct 2026 12:00:00 +0000
UTC (+00:00): 2026-10-24 12:00:00
Relative: now

How the unit is detected

A Unix timestamp doesn’t say whether it counts seconds or milliseconds. The tool guesses from the size of the number, which works because the ranges don’t overlap for any realistic date:

Absolute value	Read as	Typical source
below 10^11	seconds	Unix tools, JWT claims, most APIs
below 10^14	milliseconds	JavaScript Date.now(), Java, many databases
below 10^17	microseconds	Python time.time_ns() // 1000, some logs
10^17 and above	nanoseconds	Go UnixNano(), tracing systems

Seconds stay below 10^11 until the year 5138, so a 10-digit number is always seconds. A microsecond timestamp from a log:

{ "timestamp": "1767229200123456" }

Unit: microseconds (detected)
Seconds: 1767229200
Milliseconds: 1767229200123
ISO 8601: 2026-01-01T01:00:00.123Z
RFC 2822: Thu, 01 Jan 2026 01:00:00 +0000
UTC (+00:00): 2026-01-01 01:00:00
Relative: 10 months ago

The output says which unit was assumed, so a wrong guess is visible. Pass unit to override it. Negative timestamps are dates before 1970.

Things to ask your assistant

• “This log line has ts=1767229200123. When was that in Tokyo?”
• “The JWT in token.txt has exp: 1767229200. Has it expired?”
• “Give me the Unix timestamp for next Monday 09:00 in Europe/London for this cron test.”
• “Which of these timestamps in events.csv are in milliseconds and which in seconds?”

For JWTs specifically, the JWT debugger on this site and the jwt_decode_verify tool already convert exp, nbf and iat for you. For one-off lookups, the Unix timestamp converter shows the same fields in the browser.

Why this needs a tool

Time zone rules change. Countries move their daylight saving dates or drop daylight saving entirely, and the IANA database tracks those changes. The tool uses the time zone data of the Node.js runtime it runs on, so it knows the rules that runtime ships with. A model has a snapshot of whatever it read during training, applied by approximation.

The other reason is the clock. An agent checking whether a certificate, a token or a cache entry has expired needs the current time, and only the computer has it.

timestamp_convert is part of the devtoolbox.cc MCP server, which runs locally without network access. Setup for Claude Desktop, Claude Code, Cursor and VS Code is on the MCP install page.