mcp-time

Hosted deployment

A hosted deployment is available on Fronteir AI.

Overview

The Time MCP Server is a Model Context Protocol (MCP) server that provides AI assistants and other MCP clients with standardized tools to perform time and date-related operations. This server acts as a bridge between AI tools and a robust time-handling backend, allowing for complex time manipulations through natural language interactions.

Features

• ⏰ Time Manipulation - Get current time, convert between timezones, and add or subtract durations
• 🗣️ Natural Language Parsing - Understands relative time expressions like "yesterday" or "next month"
• ⚖️ Time Comparison - Compare two different times with ease
• 🎨 Flexible Formatting - Supports a wide variety of predefined and custom time formats
• ✅ MCP Compliance - Fully compatible with the Model Context Protocol standard
• 🔄 Multiple Transports - Supports `stdio` for local integrations and `HTTP stream` for network access

Installation

This MCP server can be integrated with various AI assistant clients that support the Model Context Protocol, including Cursor, Claude Desktop, Claude Code, and many more.

🚀 One-Click Install (Cursor)

Click the button below to automatically configure the MCP server using Docker in your Cursor environment:

Using npx (JavaScript/Node.js)

This method runs the MCP server using `npx`, which requires Node.js to be installed. Copy the following JSON configuration into your MCP client settings:

{
  "mcpServers": {
    "mcp-time": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@theo.foobar/mcp-time"
      ]
    }
  }
}

Using Docker

Run the MCP server in an isolated container. Requires Docker to be installed. Copy this JSON configuration into your MCP client settings:

{
  "mcpServers": {
    "mcp-time": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "theo01/mcp-time:latest"
      ]
    }
  }
}

Using binary

Install the `mcp-time` binary directly on your system. Choose one of the installation methods below, ensuring the binary is placed in a directory that's in your `PATH`. Then add this JSON configuration to your MCP client settings:

{
  "mcpServers": {
    "mcp-time": {
      "type": "stdio",
      "command": "mcp-time"
    }
  }
}

Option 1: Download from Releases

Download the latest pre-built binary from the releases page:

# Replace OS-ARCH with your platform (e.g., linux-amd64, darwin-arm64, windows-amd64)
curl -Lo mcp-time https://github.com/TheoBrigitte/mcp-time/releases/latest/download/mcp-time.OS-ARCH
install -D -m 755 ./mcp-time ~/.local/bin/mcp-time

Option 2: Install with Go

For Go developers, install directly using `go install`:

go install github.com/TheoBrigitte/mcp-time/cmd/mcp-time@latest

The binary will be installed in your `$GOPATH/bin` directory.

Option 3: Build from Source

Clone and build the project using `make`:

git clone https://github.com/TheoBrigitte/mcp-time.git
cd mcp-time
make install

The binary will be installed in `~/.local/bin/mcp-time`.

Usage

Basic Usage

Start with stdio transport (default, for MCP clients):

mcp-time

Start with HTTP stream transport (for network access):

mcp-time --transport stream --address "http://localhost:8080/mcp"

Command-Line Options

The server supports the following flags for advanced configurations:

$ mcp-time --help
An MCP (Model Context Protocol) server which provides utilities to work with time and dates.

Usage:
  mcp-time [flags]

Flags:
      --address string     Listen address for Stream HTTP Server (only for --transport stream) (default "http://localhost:8080/mcp")
  -h, --help               help for mcp-time
      --log-file string    Path to log file (logs is disabled if not specified)
  -t, --transport string   Transport layer: stdio, stream. (default "stdio")
      --version            Print version information and exit

Available Tools

`current_time`

Get the current time in any timezone and format.

Parameters:

• `format` (optional) - The output format (predefined like `RFC3339`, `Kitchen`, or custom Go layout)
• `timezone` (optional) - Target timezone in IANA format (e.g., `America/New_York`). Defaults to UTC

Example: "What time is it in Tokyo?"

`relative_time`

Get a time based on a relative natural language expression.

Parameters:

• `text` (required) - Natural language expression (e.g., `yesterday`, `5 minutes ago`, `next month`)
• `time` (optional) - Reference time for the expression. Defaults to current time
• `timezone` (optional) - Target timezone for the output
• `format` (optional) - Output format for the time

Example: "What was the date 3 weeks ago?"

`convert_timezone`

Convert a given time between timezones.

Parameters:

• `time` (required) - Input time string (supports various formats)
• `input_timezone` (optional) - Timezone of the input time
• `output_timezone` (optional) - Target timezone for the output
• `format` (optional) - Output format for the time

Example: "Convert 2:30 PM EST to Tokyo time"

`add_time`

Add or subtract a duration from a given time.

Parameters:

• `time` (required) - Input time string
• `duration` (required) - Duration to add/subtract (e.g., `2h30m`, `-1h`, `24h`)
• `timezone` (optional) - Target timezone for the output
• `format` (optional) - Output format for the time

Example: "What time will it be in 45 minutes?"

`compare_time`

Compare two times and determine their relationship. Supports timezone-aware comparisons.

Parameters:

• `time_a` (required) - First time to compare
• `time_a_timezone` (optional) - Timezone for `time_a` in IANA format (e.g., `America/New_York`)
• `time_b` (required) - Second time to compare
• `time_b_timezone` (optional) - Timezone for `time_b` in IANA format (e.g., `Europe/London`)

Returns:

• `-1` if `time_a` is before `time_b`
• `0` if `time_a` equals `time_b`
• `1` if `time_a` is after `time_b`

Example: "Is 3 PM EST before 8 PM GMT?"

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.

License

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

Credits

Built with these excellent libraries:

• araddon/dateparse - Parse dates without knowing the format
• tj/go-naturaldate - Natural language date parsing
• mark3labs/mcp-go - Model Context Protocol SDK for Go