worldclock-mcp

# World Clock Pro MCP server

**Give your AI agent a real clock.** Public, read-only, no API key:

```
https://worldclock.pro/mcp
```

Models cannot reliably compute local times, DST transitions, or timezone math on
their own. This server gives any MCP-capable assistant live answers from the IANA
timezone database and a 224,000+ city registry, with the answer's source page cited
in every response.

- **Live endpoint:** `https://worldclock.pro/mcp` (Streamable HTTP, stateless, JSON-RPC 2.0)
- **How-to page:** [worldclock.pro/mcp](https://worldclock.pro/mcp)
- **Server card:** [`/.well-known/mcp/server-card.json`](https://worldclock.pro/.well-known/mcp/server-card.json)
- **Registry name:** `pro.worldclock/time` (domain-verified)

## Quick connect

**Claude Code**

```bash
claude mcp add --transport http worldclockpro-time https://worldclock.pro/mcp
```

**Claude Desktop** — Settings → Connectors → *Add custom connector* → paste the URL.

**Cursor** — paste into `~/.cursor/mcp.json` (or use the button on [worldclock.pro/mcp](https://worldclock.pro/mcp)):

```json
{ "mcpServers": { "worldclockpro-time": { "url": "https://worldclock.pro/mcp" } } }
```

**VS Code**

```bash
code --add-mcp '{"name":"worldclockpro-time","type":"http","url":"https://worldclock.pro/mcp"}'
```

**ChatGPT** — Settings → *Apps & Connectors* → Advanced settings → enable *Developer
mode* → create a connector with the URL and **No authentication**. The server is
read-only, so it works on plans where custom connectors are limited to read-only tools.

**OpenClaw** — add to `openclaw.json`:

```json
{ "mcp": { "servers": { "worldclockpro-time": { "url": "https://worldclock.pro/mcp", "transport": "streamable-http" } } } }
```

**MCP Inspector**

```bash
npx @modelcontextprotocol/inspector
# Transport: "Streamable HTTP" → URL: https://worldclock.pro/mcp
```

## Tools

| Tool | What it does | Try asking |
|------|--------------|------------|
| `get_current_time` | Current time in one or many places (up to 50 at once). | *"What time is it in Tokyo, Paris, and UTC?"* |
| `convert_time` | Move one moment across time zones, DST-safe. | *"If it's 9 AM Monday in New York, what time is it in Sydney?"* |
| `time_by_coordinates` | Time at any point on Earth, by latitude/longitude. | *"What's the local time at 48.85, 2.35?"* |
| `get_dst_transitions` | DST observance and exact clock-change dates for any year. | *"When do the clocks change in London this year?"* |
| `search_cities` | Multilingual city lookup → canonical slug, IANA zone, coordinates. | *"Find cities called 'San Jose'."* |

Every result includes a `source_url` linking the matching worldclock.pro page,
so answers can cite a live source.

### Ways to describe a place

- **City name or alias** — `"Tokyo"`, `"new-york"`, `"nyc"`, `"Москва"`, `"São Paulo"`
- **Timezone** — IANA id (`"America/New_York"`) or abbreviation (`"PST"`, `"ET"`, `"UTC"`)
- **Coordinates** — latitude + longitude; the answer names the nearest city

## Use as a Claude Code plugin

This repo is itself a plugin marketplace:

```
/plugin marketplace add worldclockpro/worldclock-mcp
/plugin install world-clock@worldclockpro
```

The plugin wires up the remote MCP server and installs the `world-clock` skill,
which teaches the assistant when to use which tool and the classic timezone traps
(EST vs ET, half-hour offsets, date-line weekday changes).

## Use as an OpenClaw skill

The same skill follows the [Agent Skills](https://agentskills.io) format:

```bash
npx clawhub@latest install world-clock   # once published on ClawHub
# or copy skills/world-clock/ into your skills directory
```

## Why trust it

- **Read-only by design.** Every tool declares `readOnlyHint: true`. There are no
  write operations, no accounts, and nothing to sign in for.
- **No tracking.** Queries are computed in memory and not stored. See the
  [privacy policy](https://worldclock.pro/privacy).
- **Live IANA data.** DST rules come from the IANA timezone database, updated with
  the weekly data refresh, never hard-coded.
- **Run by an established team.** The people behind the
  [World Clock Master](https://worldclock.pro/world-clock-master) (Apple Editor's
  Choice) and [World Clock Pro](https://worldclock.pro/mac) apps.
- **Domain-verified.** The registry listing `pro.worldclock/time` is published with
  cryptographic proof of control of worldclock.pro.

## Limits and errors

- Up to **50 locations per call** (`search_cities` returns up to 25 matches).
- Per-IP rate limit: 60 calls per 10 seconds (HTTP 429 with `Retry-After` beyond that).
- Invalid input returns structured errors (`LOCATION_NOT_FOUND`, `INVALID_TIMEZONE`,
  `AMBIGUOUS_INSTANT`, ...) an agent can read and recover from.

## Links

- Website: [worldclock.pro](https://worldclock.pro)
- Agent guide: [worldclock.pro/llms.txt](https://worldclock.pro/llms.txt)
- Support: support@worldclock.pro

MIT licensed. See [SECURITY.md](SECURITY.md) for the security posture.