Time MCP Server

How to use

You connect an MCP client to Time MCP Server using a stdio transport for local integrations or an HTTP stream transport for network access. Once connected, you can perform common time operations like getting the current time in a specific timezone, converting between timezones, parsing natural language expressions like “yesterday” or “next month,” and adding or subtracting durations. You can also compare two times and format results in predefined or custom layouts.

How to install

Prerequisites vary by installation method. Ensure your environment has the required runtimes or tools for the method you choose.

# One-Click Install is available in supported environments that integrate MCP servers directly (no additional setup required here).
```

### Using npx (JavaScript/Node.js)

This method runs the MCP server using npx and requires Node.js to be installed. Use the following MCP client setting to connect via stdio:

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

### Using Docker

Run the MCP server in an isolated container. Ensure Docker is installed, then configure your MCP client as follows:

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

### Using the binary directly

Install the binary and reference it via stdio. You can prompt your client to use the binary with these options:

```json
{
  "mcpServers": {
    "mcp-time": {
      "type": "stdio",
      "command": "mcp-time",
      "args": []
    }
  }
}
```

#### Option 1: Download from Releases

```bash
# 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

```bash
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

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

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

Additional notes

The server supports multiple transports. For local development, stdio is the simplest path. For networked deployments, use the HTTP stream transport and provide the appropriate listen address and endpoint if your client requires a networked MCP connection.

Known usage patterns

Start with stdio transport for MCP clients that run in the same process or environment. Start with HTTP stream transport when you need network access to the MCP server, using the address you configure for the stream endpoint.

current_time

Get the current time in a specific timezone and format.

relative_time

Parse natural language time expressions (e.g., yesterday, next month) and return a time.

convert_timezone

Convert a given time between timezones.

add_time

Add or subtract a duration from a given time.

compare_time

Compare two times, with optional timezones, and determine their order.