timezone-mcp
timezone-mcp is a local MCP server that converts timestamps between time zones using IANA rules, including daylight saving time, and returns explicit source, UTC, and converted dates.
Exposes one tool,
convert_time, that converts a timestamp from a source timezone.Accepts ISO-like timestamps with a clock time, with or without a UTC offset; date-only values are rejected.
Lets you specify a
source_timezonefor offset-less timestamps, or omit it when the timestamp already contains an offset.Accepts an optional list of
output_timezonesfor additional conversions.Supports configured standing timezones via
TIMEZONE_MCP_ALWAYS_TIMEZONESor a JSON config file, defaulting to China and U.S. Eastern.Recognizes IANA time zone names plus short aliases such as
china,eastern,pacific,utc, andaoe.Handles ambiguous fall-back times with a
foldparameter (0 = first occurrence, 1 = second occurrence) and rejects nonexistent spring-forward times.Returns the resolved input, UTC time, configured timezones, conversions, and a
date_boundaryobject listing zones whose calendar date differs from the source.Each formatted timestamp includes
datetime,date,time,weekday,timezone,abbreviation, andutc_offset.Deduplicates zones after normalization and omits zones whose local time and offset match the source instant.
Can be registered with MCP clients like Claude Desktop, Claude Code, and Codex, and run locally via
uvx.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@timezone-mcp what time is 3pm Eastern in China?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
timezone-mcp
timezone-mcp is a local MCP server that converts timestamps between time zones. It exposes one tool, convert_time.
The server uses IANA time zone rules, including daylight saving time at the specified instant, and returns the source, UTC, and converted times with their dates.
Agents often get date boundaries wrong
As of mid-2026, general-purpose agents often answer time zone questions confidently but incorrectly. Errors are especially common around daylight saving transitions and conversions that cross a calendar date. timezone-mcp delegates the calculation to Python's IANA time zone database and returns each date explicitly.
Related MCP server: datetime-mcp
Install
Requires uv, which installs Python for the tool if the machine does not have a suitable version. Nothing to clone: add-mcp registers the server with your agent in one command, and knows where each client keeps its config.
npx add-mcp "$(command -v uvx)" \
--args --from --args git+https://github.com/osteele/timezone-mcp@v0.1.0 --args timezone-mcp \
--name timezone-mcp \
--env TIMEZONE_MCP_ALWAYS_TIMEZONES="China,Eastern" \
--global --agent claude-code --agent codexEvery argument after the command needs its own --args. add-mcp does not split a quoted command string, so folding them into the first argument writes a command name containing spaces, without reporting an error. Drop --global to register the server for one project instead of the whole machine, and see npx add-mcp list-agents for the other clients it supports.
That writes an entry equivalent to this, which you can also add by hand to whichever file your client uses:
{
"timezone-mcp": {
"command": "/absolute/path/to/uvx",
"args": [
"--from",
"git+https://github.com/osteele/timezone-mcp@v0.1.0",
"timezone-mcp"
],
"env": {
"TIMEZONE_MCP_ALWAYS_TIMEZONES": "China,Eastern"
}
}
}Claude Desktop keeps that file at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, under mcpServers; open it from the developer settings, and restart the app after editing. Claude Code and Codex also take it from their own CLIs:
claude mcp add --scope user timezone-mcp \
-e TIMEZONE_MCP_ALWAYS_TIMEZONES="China,Eastern" \
-- "$(command -v uvx)" --from git+https://github.com/osteele/timezone-mcp@v0.1.0 timezone-mcp
codex mcp add timezone-mcp \
--env TIMEZONE_MCP_ALWAYS_TIMEZONES="China,Eastern" \
-- "$(command -v uvx)" --from git+https://github.com/osteele/timezone-mcp@v0.1.0 timezone-mcp@v0.1.0 pins the install to a tagged release, so a later push to main cannot change what an already-registered client runs. Drop it to track main, or raise it when a newer tag exists.
To run the server by hand, uvx --from git+https://github.com/osteele/timezone-mcp@v0.1.0 timezone-mcp waits for MCP messages on standard input, so it will appear to hang. That is what a client expects; press Ctrl-C.
Configuration
Every result carries the zones you asked for. TIMEZONE_MCP_ALWAYS_TIMEZONES adds zones that appear in every result without being requested. With no configuration, those standing zones are China and U.S. Eastern.
Set it to a comma-separated list or a JSON array:
export TIMEZONE_MCP_ALWAYS_TIMEZONES="China,Eastern"The JSON value [] disables standing zones entirely. An empty string is rejected.
For file-based configuration, save a JSON file such as /absolute/path/to/timezone-mcp.json:
{
"always_timezones": ["China", "Eastern"]
}Then set its path:
export TIMEZONE_MCP_CONFIG=/absolute/path/to/timezone-mcp.jsonTIMEZONE_MCP_ALWAYS_TIMEZONES takes precedence when both variables are set.
Standing and requested zones are combined, and repeated names are deduplicated after normalization. A zone is dropped from the result when its local clock time and UTC offset match the source at that instant. A Los Angeles result is dropped for a Phoenix source when both are on UTC−07:00, for example, even though their daylight saving rules differ.
Tool arguments
time: An ISO-like timestamp with a clock time, such as2026-07-16 09:30,2026-07-16T09:30:00, or2026-07-16T09:30:00-04:00. Date-only values are rejected.source_timezone: The source time zone for a timestamp without a UTC offset. Omit it whentimealready contains an offset.output_timezones: An optional list of additional output time zones.fold:0selects the first occurrence of an ambiguous local time, and1selects the second occurrence during a fall daylight saving transition. The default is0.
Local times that do not exist during a spring daylight saving transition are rejected.
Time zone names
Any zone argument accepts an IANA name, such as America/Los_Angeles or Europe/Berlin.
Five zones also have short aliases, matched case-insensitively:
Zone | Aliases |
|
|
|
|
|
|
|
|
|
|
That table is the whole alias set. Anything else must be a valid IANA name; an unrecognized name is rejected with unknown timezone.
AoE is Anywhere on Earth, the fixed UTC−12 offset that conference and journal deadlines are usually quoted in. It is the last place on the planet where a given calendar date is still in progress, so a deadline stated as AoE expires later than the same wall-clock time anywhere else.
Result
The result contains the resolved input, UTC time, standing zones, conversions, and date-boundary information. Selected fields from a China-to-Eastern conversion look like this:
{
"utc": {
"datetime": "2026-07-16T01:00:00+00:00"
},
"configured_timezones": [
"Asia/Shanghai",
"America/New_York"
],
"conversions": [
{
"datetime": "2026-07-15T21:00:00-04:00",
"timezone": "America/New_York",
"abbreviation": "EDT",
"requested_timezone": "America/New_York"
}
],
"date_boundary": {
"source_date": "2026-07-16",
"different_dates": ["America/New_York"]
}
}date_boundary.different_dates names the zones whose calendar date differs from the source, which is the case these conversions most often get wrong.
Each formatted timestamp also includes date, time, weekday, abbreviation, and utc_offset fields.
Development
git clone https://github.com/osteele/timezone-mcp
cd timezone-mcp
uv sync
uv run --frozen pytest
uv run --frozen ruff check .
uv run --frozen ty checkTo point a client at a checkout rather than at the published source, replace the --from git+... argument with --directory /absolute/path/to/timezone-mcp run --no-dev, invoking uv instead of uvx.
Related
timezone-mcp is one of a set of tools for agent sessions and the environments
they run in, listed at
osteele.com/software/agent-tools.
Available Tools
1 toolconvert_timeA
Convert a timestamp from a source timezone. Returns configured default timezones plus any requested additional timezones, omitting the source timezone when it would duplicate the input.
Inputs: time (required), fold, source_timezone, output_timezones. Returns: utc, input, conversions, date_boundary, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusion or overlap. The tool's purpose is clearly defined and unambiguous.
The single tool name `convert_time` follows a clean verb_noun pattern, which is internally consistent.
The server offers just one tool, which feels thin for a general timezone utility. While the core conversion feature is present, users might expect additional operations like timezone listing or validation.
The conversion operation is fully covered, but the surface lacks an explicit way to list available timezones or configured defaults, which would be a minor gap for a timezone-focused MCP.
Maintenance
Related MCP Connectors
MCP server for time in cities around the world, time zones, DST, conversion, and meetings.
Timezone MCP — wraps timeapi.io (free, no auth)
A real clock for AI agents: current time, timezone conversion, and DST facts from the IANA tzdb.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that provides time and timezone conversion capabilities, enabling LLMs to get current time information and perform timezone conversions using IANA timezone names.2MIT
- AlicenseDqualityCmaintenanceA lightweight MCP server that provides date and time tools, including the ability to retrieve current timestamps and parse date strings with IANA timezone support. It enables AI models to interact with the host OS clock and perform temporal calculations via stdio transport.311 npm7MIT
- AlicenseNot gradedqualityDmaintenanceA timezone-aware MCP server that converts times, looks up current local times, and finds overlapping working-hour slots for distributed teams.MIT

World Clock Pro MCPofficial
AlicenseNot gradedqualityDmaintenanceA read-only MCP server that gives AI agents accurate current time, timezone conversions, DST transitions, and city lookups using live IANA timezone data, with cited sources.MIT