mcp-time

The mcp-time server exposes a set of time-related tools that can be accessed through the Model Context Protocol (MCP). It provides actions for obtaining the current time, parsing natural language time expressions, converting between time zones, adding or subtracting durations, and comparing times. The available tools include current_time, relative_time, convert_timezone, add_time, and compare_time. The server supports multiple transports, including a stdio transport for local integrations and an HTTP stream transport for network access. You can run the server directly as a standalone binary or via MCP-enabled clients, then invoke the provided tools through your MCP client by referencing the mcp-time server.

Common use patterns include asking for the current time in a specific timezone, converting a date from one zone to another, or computing the date/time after a given duration. For example you can request the current time in Tokyo, convert a given time from EST to Tokyo, or add 2 hours to a specific timestamp. The tool set is designed to be composable with natural language prompts in your MCP-enabled assistant, letting you build flows like reminders, scheduling, and time zone-aware planning.

To use via stdio (default):

• Start the server with: mcp-time
• Then connect your MCP client to the stdio channel and issue tool calls by referencing the tool names (current_time, relative_time, etc.).

To use via HTTP stream:

• Start with: mcp-time --transport stream --address "http://localhost:8080/mcp"
• Connect your MCP client to the HTTP stream endpoint and interact using the same tool names.

Prerequisites:

• A supported environment with Go tooling and/or prebuilt binaries
• Access to the internet to download releases or fetch modules

Option 1 — One-click binary (recommended for quick start):

• Download the latest release for your platform from the GitHub releases page
• Place the binary in a directory included in your PATH, for example: ~/.local/bin
• Ensure the binary is executable: chmod +x mcp-time
• Run with: mcp-time

Option 2 — Install with Go (for developers):

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

• This installs the binary to your GOPATH/bin or your Go bin path; make sure that path is in your PATH.
• Run with: mcp-time

Option 3 — Build from source (requires Git and Go):

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

• The make install target places the binary in ~/.local/bin/mcp-time (or your system's default install path).

Option 4 — Docker (alternative deployment):

• Run the container and connect via stdio or stream transport as needed. Example:

docker run --rm -i theo01/mcp-time:latest

• For MCP clients, configure the mcp-time server entry to use the docker-based tool accordingly.

Tips and common considerations:

• The server supports multiple commands: current_time, relative_time, convert_timezone, add_time, and compare_time. Each tool has its own set of parameters described in the README; mirrors/examples are provided there with typical inputs.
• If you use the HTTP stream transport, ensure the address you provide matches your network setup and that your MCP client can reach the endpoint.
• You can use the provided examples in the README as JSON templates within your MCP client configuration to wire the mcp-time server up via stdio or streaming transports.
• When running locally, ensure the binary is accessible and not blocked by security/antivirus software. Logs can be enabled via the --log-file option if you need observability.
• While the server focuses on time operations, always validate external time inputs when constructing time calculations to avoid parsing errors in edge cases.