# mcp-time-server

[Русская версия](README.ru.md)

An MCP server for time operations. Provides tools for getting the current time, converting timestamps, comparing timezones, date arithmetic, and more.

## Tools

- **get_current_time** — current time in a given timezone
- **timestamp_to_date** — Unix timestamp → human-readable date
- **date_to_timestamp** — date string → Unix timestamp
- **time_delta** — compare current time in two timezones and show the difference
- **add_time** — add or subtract days, hours, minutes from a date
- **countdown** — time remaining until a target date
- **date_info** — day of week, week number, day of year, leap year
- **day_of_week** — day of week for a date
- **week_number** — ISO week number for a date

All tools support the `timezone` parameter — any IANA timezone (e.g. `Europe/Moscow`, `America/New_York`, `UTC`).

## Configuration

| Variable | Description | Default |
|---|---|---|
| `MCP_TIME_TIMEZONE` | Default timezone | `UTC` |

## Installation

Requires [uv](https://docs.astral.sh/uv/getting-started/installation/).

### Claude Code

```bash
claude mcp add time -- uvx --from git+https://github.com/sherevv/mcp-time-server mcp-time-server
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sherevv/mcp-time-server", "mcp-time-server"],
      "env": {
        "MCP_TIME_TIMEZONE": "Europe/Moscow"
      }
    }
  }
}
```

### Cursor, Windsurf and other MCP clients

Same approach — set `uvx` as the command in your client's MCP settings.

## Updating

Clear the `uv` cache and restart your client:

```bash
uv cache clean mcp-time-server
```

On the next launch, `uvx` will fetch the latest version from the repository.

## Usage examples

After connecting, ask your assistant:

- "What time is it in Tokyo?"
- "Convert timestamp 1700000000 to a date"
- "What's the timestamp for 2025-01-01 00:00:00 in Moscow?"
- "What day of the week is 2025-12-31?"
- "How much time is left until New Year?"

## License

[MIT](LICENSE)