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)

claude mcp add timekeeper npx mcp-timekeeper

Option B: Manual configuration - Add to your Claude Code settings:

{
  "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 for development setup and contribution guidelines.

License

MIT