mcp-time

Time MCP Server

A Model Context Protocol server that enables AI assistants to interact with time

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