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.
- Flexible Formatting: Supports a wide variety of predefined and custom time formats.
- MCP Compliance: Fully compatible with the Model Context Protocol standard.
- Multiple Transports: Can be run using
stdio
for simple integrations or as anHTTP stream
server for network access.
Installation
This MCP server can be integrated with various AI assistants that support the Model Context Protocol.
On Cursor
Use the link below to install directly in Cursor.
Using Docker
Copy the following JSON configuration into your MCP client to run the server using Docker:
{
"mcpServers": {
"time": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"theo01/mcp-time:latest"
]
}
}
}
Using binary
Copy the following JSON configuration into your MCP client to run the server using the binary:
{
"mcpServers": {
"time": {
"command": "mcp-time"
}
}
}
You need to install the mcp-time
binary on your system. You can do this in several ways:
Install from releases
You can download the latest binary from the releases page.
# Replace OS-ARCH with your operating system and architecture (e.g., linux-amd64, darwin-arm64)
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
Install with Go
go install github.com/TheoBrigitte/mcp-time/cmd/mcp-time@latest
This will install the mcp-time
binary in your $GOPATH/bin
directory.
Building from Source
git clone https://github.com/TheoBrigitte/mcp-time.git
cd mcp-time
make install
This will build and install the mcp-time
binary in the ~/.local/bin
directory.
Usage
Basic Usage
Start the MCP server with the default stdio
transport:
mcp-time
Start the MCP server with the stream
transport:
mcp-time --transport stream --address "http://localhost:8080/mcp"
Advanced Usage
The server supports several command-line options for more 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
relative_time
Get a time based on a relative natural language expression.
Parameters:
text
(required): The natural language expression (e.g.,yesterday
,5 minutes ago
,next month
).time
(optional): A reference time for the relative expression. Defaults to current time.timezone
(optional): The target timezone for the output.format
(optional): The output format for the time.
convert_timezone
Convert a given time between timezones.
Parameters:
time
(required): The input time string. It can be in various formats.input_timezone
(optional): The timezone of the input time.output_timezone
(optional): The target timezone for the output.format
(optional): The output format for the time.
current_time
Get the current time.
Parameters:
format
(optional): The output format for the time. Can be a predefined format (e.g.,RFC3339
,Kitchen
) or a custom Go layout.timezone
(optional): The target timezone in IANA format (e.g.,America/New_York
). Defaults to UTC.
add_time
Add or subtract a duration to a given time.
Parameters:
time
(required): The input time string.duration
(required): The duration to add or subtract (e.g.,2h30m
,-1h
).timezone
(optional): The target timezone for the output.format
(optional): The output format for the time.
compare_time
Compare two times.
Parameters:
time_a
(required): The first time to compare.time_b
(required): The second time to compare.
Returns:
-1
iftime_a
is beforetime_b
.0
iftime_a
is equal totime_b
.1
iftime_a
is aftertime_b
.