<p align="center"><img src="logo.png" alt="timezone-toolkit" width="120" height="120"></p>

# 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](https://modelcontextprotocol.io) 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`](https://registry.modelcontextprotocol.io/v0/servers?search=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:

```
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`](https://www.npmjs.com/package/countries-and-timezones)
(IANA data) and [`chrono-node`](https://www.npmjs.com/package/chrono-node)
(natural language). Public holidays via the free
[Nager.Date](https://date.nager.at) API. No native binaries.

## License

[MIT](./LICENSE) © AgisHub