mcp-timekeeper/README.md

MCP server for timezone conversion and time utilities

# MCP Timekeeper

A Model Context Protocol (MCP) server that provides timezone conversion and Unix timestamp utilities for Claude Code and other MCP-compatible AI systems.

## Features

This MCP server provides eight powerful time-related tools:

- **convert_time**: Convert times between different timezones
- **time_to_unix**: Convert ISO date strings to Unix timestamps  
- **get_current_time**: Get current time in any timezone
- **get_client_time**: Get the current time and timezone of the client/server system
- **add_time**: Add or subtract time periods from a date
- **time_difference**: Calculate the time difference between two dates
- **format_time**: Format dates/times in various formats and locales
- **timezone_info**: Get detailed information about any timezone

### Setup MCP Server

**Option A: Using Claude MCP add command (recommended)**
```bash
claude mcp add timekeeper npx mcp-timekeeper
```

**Option B: Manual configuration** - Add to your Claude Code settings:
```json
{
  "mcpServers": {
    "timekeeper": {
      "command": "npx",
      "args": ["mcp-timekeeper"]
    }
  }
}
```


## Available Tools

Once configured, Claude Code will have access to these tools:

### `convert_time`
Convert time from one timezone to another.

**Parameters:**
- `source_timezone`: Source timezone (e.g., "America/New_York", "UTC")
- `time`: Time in HH:MM format or ISO datetime format
- `target_timezone`: Target timezone (e.g., "Asia/Tokyo", "Europe/London")

**Example:**
```
Convert 2:30 PM from New York time to Tokyo time
```

### `time_to_unix` 
Convert ISO date string to Unix timestamp.

**Parameters:**
- `iso_date`: ISO date string (e.g., "2023-12-25T10:30:00")
- `timezone` (optional): Timezone to interpret the date in

**Example:**
```
Convert 2023-12-25T10:30:00 to Unix timestamp
```

### `get_current_time`
Get current time in specified timezone.

**Parameters:**
- `timezone` (optional): Timezone (defaults to system timezone)

**Example:**
```
What time is it right now in London?
```

### `get_client_time`
Get the current time and timezone of the client/server system.

**Example:**
```
What is the current time and timezone of this system?
```

### `add_time`
Add or subtract time periods from a date.

**Parameters:**
- `date`: ISO date string (e.g., "2023-12-25T10:30:00")
- `amount`: Amount to add (positive) or subtract (negative)
- `unit`: Time unit ("years", "months", "days", "hours", "minutes", "seconds")
- `timezone` (optional): Timezone to interpret the date in

**Example:**
```
What date is 45 days from December 25, 2023?
```

### `time_difference`
Calculate the time difference between two dates.

**Parameters:**
- `start_date`: Start date in ISO format
- `end_date`: End date in ISO format
- `unit` (optional): Unit to express difference in ("days", "hours", etc.)
- `timezone` (optional): Timezone to interpret dates in

**Example:**
```
How many days between Christmas and New Year's Day?
```

### `format_time`
Format a date/time in various formats and locales.

**Parameters:**
- `date`: ISO date string to format
- `format`: Format pattern ("full", "long", "medium", "short", "date", "time", "iso", or custom like "YYYY-MM-DD HH:mm:ss")
- `timezone` (optional): Timezone to format in
- `locale` (optional): Locale for formatting (e.g., "en-US", "fr-FR")

**Example:**
```
Format December 25, 2023 10:30 AM in French locale
```

### `timezone_info`
Get detailed information about any timezone.

**Parameters:**
- `timezone`: Timezone identifier (e.g., "America/New_York")
- `date` (optional): Date to get timezone info for (defaults to current)

**Example:**
```
Tell me about the Eastern Time timezone
```

## Timezone Support

The server supports all standard timezone identifiers, including:
- IANA timezone names: `America/New_York`, `Europe/London`, `Asia/Tokyo`
- UTC and GMT: `UTC`, `GMT`
- Abbreviated zones: `EST`, `PST`, etc.

## Examples

### Basic Time Conversion
```
User: "What time is 3:00 PM EST in California?"
Claude: [Uses convert_time tool] "3:00 PM EST = 12:00 PM PST (-3 hours difference)"
```

### Unix Timestamp Conversion
```
User: "Convert December 25, 2023 10:30 AM to Unix timestamp"
Claude: [Uses time_to_unix tool] "Unix timestamp: 1703505000"
```

### Current Time Queries
```
User: "What time is it in Tokyo right now?"
Claude: [Uses get_current_time tool] "Current time: 2023-12-01T15:30:45 (Asia/Tokyo)"
```

### Date Calculations
```
User: "What date is 3 months from today?"
Claude: [Uses add_time tool] "2024-03-01T08:30:45 (America/Denver) - Added 3 months"
```

### Time Differences
```
User: "How many hours between 2023-12-25T09:00:00 and 2023-12-25T17:30:00?"
Claude: [Uses time_difference tool] "8.5 hours later"
```

### Date Formatting
```
User: "Format 2023-12-25T15:30:00 in full format for French locale"
Claude: [Uses format_time tool] "lundi 25 décembre 2023 à 15:30:00 UTC"
```

## Requirements

- Node.js (ES modules enabled)
- Claude Code or other MCP-compatible client

## Contributing

See [DEVELOPMENT.md](./DEVELOPMENT.md) for development setup and contribution guidelines.

## License

MIT