timezone-toolkit

Timezone converter, world clock, date math & meeting scheduler MCP server for AI agents — free, no API key, IANA/DST-accurate.

A remote Model Context Protocol server that gives AI agents everything they can't compute on their own about time: the current time anywhere, timezone conversion (ISO or natural language), DST-aware date arithmetic, and cross-timezone meeting scheduling. Runs with low global latency, or locally as an npm binary.

Keywords: timezone · mcp · world clock · date math · meeting scheduler · DST · IANA · timezone converter

MCP Registry: com.agishub/timezone-toolkit

Why timezone-toolkit

• 🆓 Free & keyless — no account, no API key, no per-call billing.
• 🌍 IANA / DST accurate — correct across daylight-saving boundaries and fractional offsets (India +05:30, Nepal +05:45, Chatham +12:45).
• 🗣️ Natural language — "next Tuesday 3pm" works as well as ISO 8601.
• 🧭 No identifiers required — lookup_timezone("Delhi") → Asia/Kolkata.
• 🤝 Meeting scheduler — overlapping working-hour slots across zones, skipping weekends and public holidays.
• ⚡ Global edge — deployed globaly

Tools

Tool	Parameters	Description
now_in	timezone	Current local time in an IANA zone with utcOffset, abbreviation, isDST.
convert_timezone	datetime, from, to	Convert a time between zones. datetime accepts ISO 8601 or natural language.
convert_batch	datetime, from, to[]	Convert one instant into many target zones at once (world-clock view).
tz_offset	timezone, instant?	Exact UTC offset at an instant (DST-aware). Defaults to now.
list_timezones	query?	List/search valid IANA zone names by substring.
lookup_timezone	city_or_country	Resolve a city/country/ISO code to its IANA zone(s).
date_math	datetime, timezone, operation	Add/subtract time (DST-aware) or diff two datetimes across zones.
find_meeting_slots	participants[], duration, date_range	Best overlapping working-hour slots; skips weekends & holidays.
is_holiday	date, country_code	Whether a date is a public holiday (ISO 3166-1 alpha-2).

All responses are JSON. Where applicable they include datetime (ISO 8601), utcOffset, abbreviation and isDST. Errors return { "error": "..." } with a clear message and, for bad timezones, the closest suggestions.

Response examples

now_in({ "timezone": "Asia/Kolkata" }):

{
  "timezone": "Asia/Kolkata",
  "datetime": "2026-07-10T01:37:48+05:30",
  "date": "2026-07-10",
  "time": "01:37:48",
  "weekday": "Friday",
  "utcOffset": "+05:30",
  "abbreviation": "GMT+5:30",
  "isDST": false,
  "unix": 1783626468
}

convert_timezone({ "datetime": "next Tuesday 3pm", "from": "Europe/Madrid", "to": "America/New_York" }):

{
  "input": "next Tuesday 3pm",
  "interpreted_as": "next Tuesday 3pm",
  "natural_language": true,
  "from": { "timezone": "Europe/Madrid", "datetime": "2026-07-14T15:00:00+02:00", "utcOffset": "+02:00", "abbreviation": "GMT+2", "isDST": true },
  "to":   { "timezone": "America/New_York", "datetime": "2026-07-14T09:00:00-04:00", "utcOffset": "-04:00", "abbreviation": "EDT", "isDST": true }
}

find_meeting_slots(...) (abbreviated):

{
  "duration_minutes": 60,
  "slots": [
    {
      "start_utc": "2026-07-13T13:00:00.000Z",
      "end_utc": "2026-07-13T14:00:00.000Z",
      "participants": [
        { "timezone": "Europe/Madrid", "local_start": "2026-07-13 15:00", "weekday": "Monday" },
        { "timezone": "America/New_York", "local_start": "2026-07-13 09:00", "weekday": "Monday" }
      ]
    }
  ],
  "count": 1
}

Prompt examples

• "What time is it in Tokyo right now?"
• "Convert next Tuesday 3pm New York time to Madrid and London."
• "What's the UTC offset in Kathmandu today?"
• "Which timezone is Buenos Aires in?"
• "Add 3 business-affecting days: what is 2026-10-24 12:00 Madrid plus 1 day (across DST)?"
• "Find a 60-minute meeting slot next week for people in Madrid, New York and Tokyo."
• "Is 2026-12-25 a holiday in Spain?"

Install

Remote server (recommended — nothing to install)

Point your MCP client at the hosted endpoint:

https://timezone-toolkit.agishub.com/mcp

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json, ~/.cursor/mcp.json, or Windsurf mcp_config.json):

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": ["mcp-remote", "https://timezone-toolkit.agishub.com/mcp"]
    }
  }
}

Clients with native remote support can add the URL directly (Streamable HTTP). A legacy SSE endpoint is available at /sse.

Local server (npm / stdio)

npx @agishub/timezone-toolkit

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": ["-y", "@agishub/timezone-toolkit"]
    }
  }
}

Development

npm install --legacy-peer-deps
npm test          # unit tests (DST + fractional offsets + scheduler)
npm run dev       # local Worker at http://localhost:8787/mcp
npm run deploy    # deploy to Cloudflare
npm run build     # bundle the stdio binary to dist/

Built on Intl.DateTimeFormat + countries-and-timezones (IANA data) and chrono-node (natural language). Public holidays via the free Nager.Date API. No native binaries.

License

MIT © AgisHub