Timezone Toolkit

Official9 tools

by agishub · TypeScript

Timezone converter, world clock, date math & meeting scheduler for AI agents. No API key.

Topics

ai-agentscloudflare-workersdate-mathdstianamcpmeeting-schedulermodel-context-protocoltimezonetimezone-converterworld-clock

Captured live from the server via tools/list.

now_in

Current local time in an IANA timezone, with UTC offset, abbreviation and DST flag. Use whenever you need to know 'now'.

Parameters1

timezone

string

required

IANA timezone, e.g. 'Europe/Madrid', 'Asia/Kolkata'.

Raw schema

{
  "type": "object",
  "properties": {
    "timezone": {
      "type": "string",
      "description": "IANA timezone, e.g. 'Europe/Madrid', 'Asia/Kolkata'."
    }
  },
  "required": [
    "timezone"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

convert_timezone

Convert a date/time from one IANA timezone to another. Accepts ISO 8601 or natural language ('next Tuesday 3pm'). Returns converted datetime, offset, abbreviation and DST flag.

Parameters3

datetime	string	required	ISO 8601 or natural language, e.g. "2026-07-09T15:30" or "next Tuesday 3pm".
from	string	required	Source IANA timezone.
to	string	required	Target IANA timezone.

Raw schema

{
  "type": "object",
  "properties": {
    "datetime": {
      "type": "string",
      "description": "ISO 8601 or natural language, e.g. \"2026-07-09T15:30\" or \"next Tuesday 3pm\"."
    },
    "from": {
      "type": "string",
      "description": "Source IANA timezone."
    },
    "to": {
      "type": "string",
      "description": "Target IANA timezone."
    }
  },
  "required": [
    "datetime",
    "from",
    "to"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

convert_batch

Like convert_timezone but converts a single instant into many target timezones at once. Ideal for world-clock views.

Parameters3

datetime	string	required	ISO 8601 or natural language.
from	string	required	Source IANA timezone.
to	array	required	List of target IANA timezones.

Raw schema

{
  "type": "object",
  "properties": {
    "datetime": {
      "type": "string",
      "description": "ISO 8601 or natural language."
    },
    "from": {
      "type": "string",
      "description": "Source IANA timezone."
    },
    "to": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "List of target IANA timezones."
    }
  },
  "required": [
    "datetime",
    "from",
    "to"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

tz_offset

Exact UTC offset of a timezone at a given instant (DST-aware). Handles fractional offsets like India +05:30 and Nepal +05:45.

Parameters2

timezone	string	required	IANA timezone.
instant	string	optional	ISO 8601 or natural language. Defaults to now.

Raw schema

{
  "type": "object",
  "properties": {
    "timezone": {
      "type": "string",
      "description": "IANA timezone."
    },
    "instant": {
      "type": "string",
      "description": "ISO 8601 or natural language. Defaults to now."
    }
  },
  "required": [
    "timezone"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_timezones

List or search valid IANA timezone names. Filter by city, region or country substring (e.g. 'kolkata', 'america').

Parameters1

query

string

optional

Case-insensitive substring filter.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Case-insensitive substring filter."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

lookup_timezone

Resolve a city or country name to its IANA timezone(s), so you don't need the exact identifier. E.g. 'Delhi' -> Asia/Kolkata.

Parameters1

city_or_country

string

required

City or country name, or ISO country code.

Raw schema

{
  "type": "object",
  "properties": {
    "city_or_country": {
      "type": "string",
      "description": "City or country name, or ISO country code."
    }
  },
  "required": [
    "city_or_country"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

date_math

Add/subtract time to a date respecting DST (days are calendar-based, hours/minutes are absolute), or compute the difference between two datetimes in different zones.

Parameters3

datetime	string	required	Base datetime: ISO 8601 or natural language.
timezone	string	required	IANA timezone the base datetime is in.
operation	object	required	Operation to perform.

Raw schema

{
  "type": "object",
  "properties": {
    "datetime": {
      "type": "string",
      "description": "Base datetime: ISO 8601 or natural language."
    },
    "timezone": {
      "type": "string",
      "description": "IANA timezone the base datetime is in."
    },
    "operation": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "add",
            "diff"
          ]
        },
        "amount": {
          "type": "number",
          "description": "For 'add': amount to add (negative subtracts)."
        },
        "unit": {
          "type": "string",
          "enum": [
            "seconds",
            "minutes",
            "hours",
            "days",
            "weeks"
          ],
          "description": "For 'add': seconds|minutes|hours|days|weeks."
        },
        "to_datetime": {
          "type": "string",
          "description": "For 'diff': the other datetime."
        },
        "to_timezone": {
          "type": "string",
          "description": "For 'diff': timezone of to_datetime (defaults to timezone)."
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false,
      "description": "Operation to perform."
    }
  },
  "required": [
    "datetime",
    "timezone",
    "operation"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

find_meeting_slots

Suggest the best overlapping working-hour slots for a meeting across timezones. Excludes weekends and (if a country code is given per participant) public holidays.

Parameters4

participants	array	required
duration	number	required	Meeting duration in minutes.
date_range	object	required	Search window, e.g. {"start":"2026-07-13","end":"2026-07-17"}.
limit	number	optional	Max slots to return (default 8).

Raw schema

{
  "type": "object",
  "properties": {
    "participants": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "timezone": {
            "type": "string",
            "description": "Participant IANA timezone."
          },
          "working_hours": {
            "type": "object",
            "properties": {
              "start": {
                "type": "string"
              },
              "end": {
                "type": "string"
              }
            },
            "required": [
              "start",
              "end"
            ],
            "additionalProperties": false,
            "description": "Local working hours, e.g. {\"start\":\"09:00\",\"end\":\"17:00\"}. Defaults 09:00-17:00."
          },
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 to skip that person's holidays."
          }
        },
        "required": [
          "timezone"
        ],
        "additionalProperties": false
      },
      "minItems": 1
    },
    "duration": {
      "type": "number",
      "description": "Meeting duration in minutes."
    },
    "date_range": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string"
        },
        "end": {
          "type": "string"
        }
      },
      "required": [
        "start",
        "end"
      ],
      "additionalProperties": false,
      "description": "Search window, e.g. {\"start\":\"2026-07-13\",\"end\":\"2026-07-17\"}."
    },
    "limit": {
      "type": "number",
      "description": "Max slots to return (default 8)."
    }
  },
  "required": [
    "participants",
    "duration",
    "date_range"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

is_holiday

Check whether a date is a public holiday in a country (ISO 3166-1 alpha-2). Data from the free Nager.Date service.

Parameters2

date	string	required	Date "YYYY-MM-DD".
country_code	string	required	ISO country code, e.g. "US", "ES", "IN".

Raw schema

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "description": "Date \"YYYY-MM-DD\"."
    },
    "country_code": {
      "type": "string",
      "description": "ISO country code, e.g. \"US\", \"ES\", \"IN\"."
    }
  },
  "required": [
    "date",
    "country_code"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md6 KBView on GitHub

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" }):

json

{
  "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" }):

json

{
  "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):

json

{
  "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:

code

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

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

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)

bash

npx @agishub/timezone-toolkit

json

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

Development

bash

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

Install

Tools (9)

now_inconvert_timezoneconvert_batchtz_offsetlist_timezoneslookup_timezonedate_mathfind_meeting_slots

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

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

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.