tz-mcp

Official registry Maps, travel and weather

Timezone toolkit: convert and compare instants across IANA zones with DST-safe arithmetic

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @nopilot/tz-mcp
Claude Code
claude mcp add tz-mcp -- npx -y @nopilot/tz-mcp@1.0.1
JSON configuration (Claude Desktop, Cursor, VS Code)
{
    "mcpServers": {
        "tz-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@nopilot/tz-mcp@1.0.1"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. temporal-tools
  2. Packages
  3. MCP servers
  4. Engines (library use)
  5. Development
  6. Dependencies & licenses
  7. License
  8. 中文说明

temporal-tools

Deterministic temporal tool family — cron and timezone/timezone-DST utilities as npm engines and local-first MCP servers. Same input, same output, every time: zero LLM calls, zero network requests, zero external data sources. All timezone math runs against the IANA tzdata bundled with your Node.js runtime.

为什么做这个 / Why: LLMs are famously unreliable at cron math and timezone math. These tools give agents (and humans) a deterministic oracle instead of a guess.

中文说明见 § 中文说明。

Packages

PackageWhat it isnpm
@nopilot/cron-engineValidate cron (5 & 6-field), compute next-N fire times in any IANA timezone, render human-readable explanations (English/中文)publishable engine
@nopilot/tz-engineInstant & wall-clock conversion with DST gap/overlap classification, per-year DST transition lists, cross-timezone meeting-window searchpublishable engine
@nopilot/cron-mcpMCP server exposing the cron engine as tools (cron_validate, cron_next_runs, cron_describe)publishable server
@nopilot/tz-mcpMCP server exposing the tz engine as tools (tz_validate_zone, tz_convert_instant, tz_convert_local_time, tz_dst_transitions, tz_meeting_windows)publishable server
@nopilot/mcp-server-commonShared stdio + Streamable HTTP runner (internal, not published)—

MCP servers

Both servers speak the Model Context Protocol via the official TypeScript SDK and offer two transports:

  • stdio — for local clients (Claude Code, Claude Desktop, Cursor, …): the client spawns the process.
  • Streamable HTTP — for when you prefer a local HTTP endpoint: stateless JSON-RPC POST on /mcp.
Tool catalog

cron-mcp

ToolDescription
cron_validateValidate a 5- or 6-field expression; returns normalized parts, error text, and whether dom/dow are both restricted. Supports L, ?, #nth. (W/LW are not supported — rejected deterministically.)
cron_next_runsNext N fire times (ISO-8601 UTC) anchored to any IANA timezone, searched from an explicit instant. DST gaps roll forward; ambiguous times take the later offset.
cron_describePlain-English or 简体中文 sentence explaining the expression. Template-based, deterministic.

tz-mcp

ToolDescription
tz_validate_zoneIs this a valid IANA zone name? Fail fast on typos.
tz_convert_instantOne absolute instant → local wall clock in up to 25 zones, with offsets, offset names, DST-active flag.
tz_convert_local_timeWall-clock time in one zone → all target zones, with DST edge classification (normal / ambiguous = fall-back overlap (earlier occurrence used) / gap = spring-forward (resolves forward)) and optional meeting end time.
tz_dst_transitionsAll UTC-offset transitions of a zone in a year — e.g. US Eastern 2026: forward at 2026-03-08T07:00Z (−05:00→−04:00), backward at 2026-11-01T06:00Z. Handles 30-min (Lord Howe) and 45-min (Chatham) zones.
tz_meeting_windowsSlots on a date that fall inside business hours for every participant zone (2–10 zones, 15/30/60-min steps, configurable 09:00–18:00 default).
Quick start (stdio)
// Claude Code / Claude Desktop config
{
  "mcpServers": {
    "cron": { "command": "npx", "args": ["-y", "@nopilot/cron-mcp"] },
    "tz":   { "command": "npx", "args": ["-y", "@nopilot/tz-mcp"] }
  }
}

From this repo (no npm install of published packages needed):

npm install && npm run build
node packages/cron-mcp/dist/main.js            # stdio mode
node packages/tz-mcp/dist/main.js --transport http --port 9411
# -> [mcp] listening on http://127.0.0.1:9411/mcp

HTTP mode is stateless Streamable HTTP: every POST is a self-contained JSON-RPC request (initialize not required before tools/list or tools/call). The server binds 127.0.0.1 by default and never phones home.

curl -s http://127.0.0.1:9411/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"cron_next_runs","arguments":{"expression":"*/15 9-17 * * 1-5","count":3}}}'
Why local-first (vs hosted-gateway alternatives)
temporal-toolshosted-gateway cron/tz servers (e.g. the factory-style listings)
Runs whereYour machine (stdio child process or localhost HTTP)Vendor's gateway
Network calls at runtimeNone — impossible by constructionEvery tool call round-trips to the gateway
Works offline / air-gappedYesNo
Data leaves your machineNever (expressions/timezones are still data)Query text transits vendor infra
DeterminismSame input → byte-equal output (audited by scripts/determinism-check.mjs)Depends on gateway version
Timezone dataIANA tzdata bundled with your Node.js runtimeServer-side, unknown version

Engines (library use)

import { nextRuns, describeCron, validateCron } from '@nopilot/cron-engine';

validateCron('0 30 9 * * *');            // { valid: true, fieldCount: 6, ... }
nextRuns('30 2 * * *', {                 // DST edge: 2026-03-08 02:30 America/New_York
  count: 2,
  from: '2026-03-08T00:00:00Z',
  timezone: 'America/New_York',
});                                      // runs: ['2026-03-08T07:30:00.000Z', '2026-03-09T06:30:00.000Z']
describeCron('0 9 * * 1-5', { locale: 'zh' });  // 「在上午 09:00, 星期一至星期五」

import { convertInstant, dstTransitions, meetingWindows } from '@nopilot/tz-engine';

convertInstant('2026-06-15T12:00:00Z', ['Asia/Kathmandu']);  // offset +05:45
dstTransitions('America/New_York', 2026);                    // spring 03-08, fall 11-01
meetingWindows({ participants: ['Asia/Shanghai', 'Europe/London'], date: '2026-06-15' });

Development

npm install
npm test          # build + typecheck + 57 vitest cases + determinism audit
npm run determinism   # just the byte-equal audit (22 cases, 2 fresh processes)
npm run publish:dry   # npm pack --dry-run for all publishable packages

Test coverage highlights: month-end rollover, leap-year Feb 29 (2028 vs 2026/27), L last-day/last-weekday, #nth, 2026 US spring-forward gap (03-08) and fall-back overlap (11-01), fractional offsets (+05:45 Kathmandu), sub-hour DST (Lord Howe +30min), 45-minute zones (Chatham +12:45/+13:45), and MCP protocol round trips over both transports.

Dependencies & licenses

Runtime dependencies (all permissive, no GPL/AGPL anywhere in the tree — verified against each package's npm metadata):

PackageLicenseWhy
cron-parserMITcron field parsing + next-fire iteration + timezone anchoring
cronstrueMIThuman-readable cron rendering (en + zh_CN locales)
luxonMITIANA zone math, DST gap/overlap resolution, offset names
@modelcontextprotocol/sdkMITMCP protocol layer (server + transports)
zodMITtool input schema validation
expressMITStreamable HTTP transport host

Engines wrap these libraries behind a stable, documented API; they are declared in each package's package.json and listed here per the repo's license-compliance norm.

License

MIT — see LICENSE.

中文说明

temporal-tools 是一个「确定性时间工具族」:cron 解析/下次触发计算/中英文人话解释, 加上跨时区换算/DST 切换日查询/跨时区排会,以 npm 引擎包 + 本地 MCP server 双形态提供。

三判据(产品定位,不可违背):

  1. 确定性动作工具,非 AI 包装 — 同输入必同输出(npm run determinism 做逐字节审计),零 LLM 调用;
  2. 纯本地计算 — 零外部数据源、零网络请求,时区数据用 Node.js 运行时内置的 IANA tzdata;
  3. 本地运行 — stdio 子进程或本机 HTTP(默认只绑 127.0.0.1),不走任何托管网关。

与托管网关类竞品的差异:竞品每次工具调用都要回厂商网关(隐私/离线双弱点);本项目所有计算 在你机器上完成,断网可用,表达式内容不离开本机。

已知边界:W/LW(最近工作日)修饰符不受底层 cron-parser 支持,会被确定性拒绝并返回 明确错误(不瞎猜);DST 重叠时刻(秋季回拨)取较早一次出现;DST 空洞时刻(春季跳变)向前解析。

发布步骤(面向零背景读者)见 PUBLISH.md。

Frequently asked questions

What is tz-mcp?

Timezone toolkit: convert and compare instants across IANA zones with DST-safe arithmetic

How do I install tz-mcp?

It runs on your machine. In Claude Code: claude mcp add tz-mcp -- npx -y @nopilot/tz-mcp@1.0.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does tz-mcp need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is tz-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains tz-mcp?

It is published by latbert. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.