mcp-server-time 0.3.0

A comprehensive Model Context Protocol (MCP) server for timezone-aware time operations
mcp-server-time-0.3.0 is not a library.

🕐 Time MCP Server

Crates.io Documentation License: MIT

A comprehensive Model Context Protocol (MCP) server that provides timezone-aware time operations with smart completion, automatic DST handling, and local timezone detection.

✨ Features

  • 🌍 Global Timezone Support - Works with all 400+ IANA timezones
  • 🔄 Time Conversion - Convert time between different timezones
  • 🎯 Smart Completion - Fuzzy matching for timezone names and time formats
  • 🌅 Automatic DST Handling - Seamlessly handles daylight saving transitions
  • 📍 Local Timezone Detection - Automatically detects system timezone
  • 🛡️ Robust Error Handling - Comprehensive error messages with suggestions
  • 🧹 Input Sanitization - Automatically trims whitespace from inputs
  • 📚 Rich Documentation - Built-in help and timezone references
  • 🚀 Interactive Prompts - Guided timezone conversion with completion
  • 🔧 Optional Logging - Configurable logging via LOG_LEVEL environment variable

🚀 Installation & Usage

Install from Crates.io

cargo install mcp-server-time

Run the Server

# Start the MCP server (communicates via stdio)
mcp-server-time

Test with MCP Inspector

# Install and run the MCP Inspector to test the server
npx @modelcontextprotocol/inspector mcp-server-time

Use with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "time": {
      "command": "mcp-server-time",
      "args": [],
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

🛠️ Available Tools

Smart Completion Features

NEW in v0.2.0: The server now provides intelligent completion for:

  • Timezone Names: Fuzzy matching (e.g., "ny" → "America/New_York", "tok" → "Asia/Tokyo")
  • Time Formats: All 15-minute intervals (00:00, 00:15, 00:30, 00:45, etc.)
  • Context-Aware: Suggestions adapt based on what you're typing

Tools

get_current_time

Get the current time in any IANA timezone.

Parameters:

  • timezone (string): IANA timezone name (e.g., "America/New_York", "Europe/London")

Example Request:

{
  "timezone": "Asia/Tokyo"
}

Example Response:

{
  "timezone": "Asia/Tokyo",
  "datetime": "2025-01-15T14:30:00+09:00",
  "day_of_week": "Monday",
  "is_dst": false
}

convert_time

Convert time between different timezones.

Parameters:

  • source_timezone (string): Source IANA timezone name
  • time (string): Time in 24-hour format (HH:MM)
  • target_timezone (string): Target IANA timezone name

Example Request:

{
  "source_timezone": "America/Los_Angeles",
  "time": "09:00",
  "target_timezone": "Europe/Paris"
}

Example Response:

{
  "source": {
    "timezone": "America/Los_Angeles",
    "datetime": "2025-01-15T09:00:00-08:00",
    "day_of_week": "Monday",
    "is_dst": false
  },
  "target": {
    "timezone": "Europe/Paris",
    "datetime": "2025-01-15T18:00:00+01:00",
    "day_of_week": "Monday",
    "is_dst": false
  },
  "time_difference": "+9h"
}

💬 Available Prompts

timezone_guidance

Get comprehensive guidance on timezone best practices, IANA naming conventions, and DST handling.

timezone_conversion ⭐ NEW

Interactive timezone conversion with smart completion support. This prompt provides:

  • Fuzzy timezone matching: Type partial names for suggestions
  • Time format completion: Get suggestions for valid time formats
  • Rich conversion results: Detailed information with DST status

Parameters:

  • source_timezone (string): Source IANA timezone (with completion)
  • time (string): Time in HH:MM format (with completion)
  • target_timezone (string): Target IANA timezone (with completion)

📚 Available Resources

time://status

Current server status, local timezone, and system information.

time://help

Comprehensive help documentation with examples and best practices.

time://timezones

List of common IANA timezone names organized by region.

🌐 Supported Timezones

The server dynamically supports all 400+ IANA timezone names from chrono-tz. The completion system provides fuzzy matching for easy discovery. Here are some common examples:

Americas

  • America/New_York - Eastern Time
  • America/Los_Angeles - Pacific Time
  • America/Chicago - Central Time
  • America/Toronto - Eastern Time (Canada)
  • America/Sao_Paulo - Brazil Time

Europe

  • Europe/London - Greenwich Mean Time
  • Europe/Paris - Central European Time
  • Europe/Berlin - Central European Time
  • Europe/Moscow - Moscow Time

Asia

  • Asia/Tokyo - Japan Standard Time
  • Asia/Shanghai - China Standard Time
  • Asia/Kolkata - India Standard Time
  • Asia/Dubai - Gulf Standard Time

Special

  • UTC - Coordinated Universal Time
  • GMT - Greenwich Mean Time

🔧 Configuration

Environment Variables

NEW in v0.3.0: Optional logging configuration

  • LOG_LEVEL (optional): Set logging level (debug, info, warn, error). If not set, logging is disabled for better performance.
# Run without logging (default)
mcp-server-time

# Run with debug logging
LOG_LEVEL=debug mcp-server-time

# Run with info logging
LOG_LEVEL=info mcp-server-time

Timezone Detection

The server automatically detects your local timezone. You can override this by setting environment variables or using the builder pattern (if implemented).

📖 Usage Examples

With Claude Desktop

Once configured, you can ask Claude:

"What time is it in Tokyo right now?"

"Convert 2 PM Los Angeles time to London time"

"What's the time difference between New York and Sydney?"

"Use the timezone conversion prompt to convert 14:30 from Europe/London to Asia/Tokyo"

NEW: Try the interactive timezone_conversion prompt for guided conversion with smart completion!

With MCP Inspector

# Test the server with smart completion
npx @modelcontextprotocol/inspector mcp-server-time

Try these features:

  1. Tools: Use get_current_time or convert_time
  2. Prompts: Try timezone_conversion with smart completion:
    • Type "ny" in timezone fields → see "America/New_York" suggested
    • Type "14" in time field → see "14:00", "14:15", "14:30", "14:45" suggested
  3. Resources: Browse time://help for documentation

Command Line Testing

The MCP protocol requires proper initialization. Use the MCP Inspector for testing:

# Use MCP Inspector for interactive testing
npx @modelcontextprotocol/inspector mcp-server-time

# Or test with a proper MCP client that handles the initialization handshake

Note: Direct stdio testing requires implementing the full MCP protocol handshake (initialize → tools/list → tools/call).

🚨 Error Handling

The server provides detailed error messages for common issues:

  • Invalid Timezone: Suggests similar timezone names
  • Invalid Time Format: Shows expected format (HH:MM)
  • Ambiguous Time: Handles DST transition edge cases
  • Resource Not Found: Lists available resources

🧪 Testing

Run the test suite:

cargo test

Run with coverage:

cargo tarpaulin --out html

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

  1. Clone the repository
  2. Install Rust (1.70+ required)
  3. Run cargo build
  4. Run cargo test

Code Style

This project follows the Rust standard formatting. Run cargo fmt before submitting.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

📞 Support