Skip to content

About

Time anywhere, DST-safe conversions, holidays for 200+ countries, business days and meeting slots.

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

World Time

CI npm downloads OpenSSF Scorecard License: MIT

Time and calendar answers agents get wrong. Language models do date arithmetic from memory: they put London one hour off in the weeks when the US has changed its clocks and the UK has not, convert a time that a daylight-saving change skips, count Christmas as a working day, or put Saudi Arabia's weekend on Saturday and Sunday. World Time answers from the time zone database built into Node and holiday rules for 207 countries and their states:

  • Places the way people write them: "Portland, Maine", "Munich", "Japan", "PST", "UTC+5:30" or "America/New_York". Every answer names the zone it used; a country with several offsets says so.
  • Daylight saving handled, not guessed: a local time that a spring-forward change skips, or a fall-back change repeats, is flagged with both readings. "EST" written in July is noted as EDT.
  • Holidays and business days: public holidays by country, state or city, substitute days, multi-day holidays one row per day, each country's own weekend (Friday and Saturday in Saudi Arabia), and business-day counts that list what they skipped.
  • Meetings across zones: windows inside everyone's working hours over up to two weeks, skipping each person's weekend and holidays, or the closest time when nothing fits.

Everything runs locally: no network call, no key, answers in milliseconds. Holidays on the Islamic calendar are astronomical estimates (the official day follows a moon sighting and can move by one) and are marked estimated.

Built and maintained by Arhan Canli.

Install

Install in Cursor Install in VS Code Install in Goose

Needs Node.js 20 or newer. No account or key.

Claude Code

claude mcp add world-time -- npx -y world-time-mcp

Claude Desktop: download world-time-mcp-<version>.mcpb from the latest release and open it. The bundle is signed; verify it with gh attestation verify <file> --repo arhancanli/world-time-mcp.

Any other client (Windsurf, Zed, Cline, Continue and others), in its MCP config file:

{
  "mcpServers": {
    "world-time": {
      "command": "npx",
      "args": [
        "-y",
        "world-time-mcp"
      ]
    }
  }
}

Docker

docker build -t world-time-mcp https://github.com/arhancanli/world-time-mcp.git && docker run -i --rm world-time-mcp

Hosted (Streamable HTTP): node src/server.mjs --http serves stateless MCP at POST /mcp (port from PORT, default 3000).

Example

An agent calls world_time with:

{
  "places": [
    "London",
    "Dubai"
  ],
  "time": "2026-03-08 02:30",
  "from": "New York"
}

and gets back (recorded from the live server on 2026-09-26):

{
  "utc": "2026-03-08 07:30",
  "from": {
    "place": "New York, US",
    "zone": "America/New_York",
    "date": "2026-03-08",
    "time": "03:30",
    "weekday": "Sunday",
    "utc_offset": "-04:00",
    "dst": true,
    "abbreviation": "EDT"
  },
  "status": "skipped",
  "note": "02:30 does not exist in New York, US on 2026-03-08: clocks jump forward past it. Converted 03:30, the time a clock shows at that moment.",
  "results": [
    {
      "place": "London, GB",
      "zone": "Europe/London",
      "date": "2026-03-08",
      "time": "07:30",
      "weekday": "Sunday",
      "utc_offset": "+00:00",
      "dst": false,
      "abbreviation": "GMT",
      "next_change": "2026-03-29 01:00 to +01:00"
    },
    {
      "place": "Dubai, AE",
      "zone": "Asia/Dubai",
      "date": "2026-03-08",
      "time": "11:30",
      "weekday": "Sunday",
      "utc_offset": "+04:00",
      "dst": false,
      "abbreviation": "GST"
    }
  ]
}

Tools

Tool What it does
business_days Adds business days to a date (add: 10 or -5) or counts them to an end date, skipping the local weekend (Fri-Sat in Saudi Arabia) and public holidays.
date_info Weekday, ISO week, day of year and leap year of a date ('today' = UTC); optionally the date after adding '+1 month' (month ends clamp) and the days until another date.
holidays Holidays of a country, state or city for a year, or whether one date is a working day, with the next holidays. 207 countries; Islamic-calendar dates are estimates.
meeting_slots Use for any meeting across time zones: windows inside everyone's working hours (09:00-17:00 unless given) over up to 14 days, skipping weekends and holidays, else the closest time.
world_time Time now in up to 20 places, or a local time in from converted to them ('2026-03-08 02:30', '9am'). Flags times DST skips or repeats; gives each place's offset and next clock change. Places: city, country, zone, PST, UTC+4.

How it behaves

  • Offline and read-only: no network call at all (factory.allowHosts is empty), nothing written, nothing logged except unexpected failures (to stderr, without your inputs).
  • Time zones come from the ICU database inside Node, so they are as current as your Node release.
  • Business days: the start date is never counted when adding (1 business day after Friday is Monday); when counting between two dates, both ends count if they are working days. A holiday that starts in the afternoon (Christmas Eve from 14:00 in Germany) leaves the day a working day and is noted.
  • Weekends come from the Unicode CLDR week data; pass weekend to override one.
  • Results are compact JSON with a matching output schema.

Benchmark

Measured 2026-09-26 with gpt-5.4-mini, 13 fixed tasks graded by fixed checks (bench/tasks.json, raw results in bench/results/).

Server Correct Input tokens Output tokens Tool calls Median time
This server 13/13 24880 573 14 1.9 s
mcp-server-time, the official reference time server 8/13 9843 565 15 1.7 s

Performance

Measured 2026-09-26 from Dubai, home connection against the live upstream, Node 24.19.0 (bench/perf.json, scripts/perf.mjs in the factory).

Call First call Repeat Result size
world_time: now in 5 places (city, ambiguous city, country, abbreviation, offset) 7 ms 1.5 ms 1,123 chars
world_time: a time the spring-forward change skips 5 ms 0.6 ms 718 chars
holidays: Saudi Arabia 2026 (multi-day Eid, estimated) 7 ms 0.3 ms 918 chars
business_days: 5 business days in Saudi Arabia across Eid 7 ms 0.2 ms 450 chars
meeting_slots: New York, London, Berlin over Christmas 27 ms 8.2 ms 400 chars
date_info: Jan 31 plus one month, days to Christmas 2 ms 0.2 ms 269 chars

First call: a fresh server process, including the TLS connection and the upstream's own time. Repeat: the same call again, answered from the in-process cache, so it shows this server's own overhead.

Tool definitions the model reads on every turn (name, description, input schema): 2,924 characters, against 1,002 for mcp-server-time, the official reference time server. The full tool list, with the output schemas and annotations clients use to validate results, is 4,632 characters (1,208 for the alternative).

Data sources

  • Time zones: the IANA time zone database, as shipped in Node's ICU.
  • Holidays: date-holidays (ISC; holiday data CC BY 3.0), rules for 207 countries and their states and regions.
  • Cities: city-timezones (MIT), about 7,300 cities with population, province and zone.
  • Weekends: Unicode CLDR week data, as shipped in Node.

Confirm holidays that matter legally with the official calendar: governments declare extra days off, and some holidays move.

More MCP servers by Arhan Canli

  • Web Reader: Reads web pages and PDFs as clean Markdown: main content, the sections that answer a query.
  • Actions Check: Checks GitHub Actions workflows: outdated actions, old Node runtimes, retired runners, injection.
  • Citation Check: Verifies citations: finds fabricated or mismatched references and retractions, returns clean BibTeX.
  • Config Check: Validates config files against their official schemas: tsconfig, compose, workflows, 1,400+ more.
  • Contact Check: Validates and formats phone numbers, email addresses and postal addresses for any country.
  • Cron Check: Explains cron expressions, lists next run times in any time zone, converts between cron dialects.
  • Dockerfile Check: Checks Dockerfiles: build-breaking mistakes, base image tags that exist, digests, platforms, EOL.
  • Domain Health: Email and domain checks: SPF lookup limits, DKIM keys, DMARC, DNS records, registration expiry.
  • The whole collection, 12 more

License

MIT, Copyright (c) 2026 Arhan Canli.

About

Time anywhere, DST-safe conversions, holidays for 200+ countries, business days and meeting slots.

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages