fifthseason-ai/time-mcp

Time MCP Server

A Model Context Protocol (MCP) server that provides timezone-aware time operations with natural language parsing capabilities.

Features

• Current Time: Get current time in any timezone
• Natural Language Parsing: Parse expressions like "next tuesday", "30 days from now", "tomorrow at 3pm"
• Time Calculations: Calculate differences between times
• Timezone Conversion: Convert times between different timezones
• Timezone Information: Get detailed timezone information

Tools

1. get_current_time

Get the current time in the user's timezone.

Parameters:

• timezone (optional): Timezone (e.g., 'America/New_York', 'Europe/London')
• format (optional): Output format ('YYYY-MM-DD HH:mm:ss', 'ISO', 'human')

2. parse_time_expression

Parse natural language time expressions.

Parameters:

• expression (required): Natural language time expression
• timezone (optional): Timezone for interpretation
• referenceTime (optional): Reference time for parsing

Examples:

• "next tuesday"
• "30 days from now"
• "tomorrow at 3pm"
• "last friday"
• "in 2 hours"
• "next week"

3. calculate_time_difference

Calculate the difference between two times.

Parameters:

• startTime (required): Start time (ISO string or natural language)
• endTime (required): End time (ISO string or natural language)
• timezone (optional): Timezone for interpretation
• unit (optional): Unit for the difference ('seconds', 'minutes', 'hours', 'days', 'weeks', 'months', 'years', 'human')

4. convert_timezone

Convert a time from one timezone to another.

Parameters:

• time (required): Time to convert (ISO string or natural language)
• fromTimezone (required): Source timezone
• toTimezone (required): Target timezone
• format (optional): Output format

5. get_timezone_info

Get information about a specific timezone.

Parameters:

• timezone (optional): Timezone to get information about

Configuration

The server can be configured using environment variables:

• PORT: HTTP server port (default: 3335)
• HOST: HTTP server host (default: 0.0.0.0)
• DEFAULT_TIMEZONE: Default timezone (default: America/New_York)
• LIBRECHAT_USER_ID: User ID for segmentation
• USE_TEST_MODE: Enable test mode (default: false)

Usage

As HTTP Server

PORT=3335 node index.js

As Stdio Server

node index.js

With Docker

docker build -t time-mcp .
docker run -p 3335:3335 time-mcp

Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation
• chrono-node: Natural language date parsing
• moment: Date manipulation
• moment-timezone: Timezone support
• express: HTTP server
• cors: Cross-origin resource sharing

Examples

Get Current Time

{
  "method": "tools/call",
  "params": {
    "name": "get_current_time",
    "arguments": {
      "timezone": "America/New_York",
      "format": "human"
    }
  }
}

Parse Natural Language

{
  "method": "tools/call",
  "params": {
    "name": "parse_time_expression",
    "arguments": {
      "expression": "next tuesday at 3pm",
      "timezone": "America/New_York"
    }
  }
}

Calculate Time Difference

{
  "method": "tools/call",
  "params": {
    "name": "calculate_time_difference",
    "arguments": {
      "startTime": "2024-01-01T00:00:00Z",
      "endTime": "2024-01-02T12:00:00Z",
      "unit": "human"
    }
  }
}

License

MIT