MCP Time

1<p align="center">
2    <img src="assets/mcp-time.png" alt="MCP time logo" height="100px">
3</p>
4 
5<div align="center">
6 
7[![GitHub release](https://img.shields.io/github/release/TheoBrigitte/mcp-time.svg?color)](https://github.com/TheoBrigitte/mcp-time/releases)
8[![Build Status](https://github.com/TheoBrigitte/mcp-time/actions/workflows/build.yaml/badge.svg?branch=main)](https://github.com/TheoBrigitte/mcp-time/actions/workflows/build.yaml)
9[![Go Reference](https://pkg.go.dev/badge/github.com/TheoBrigitte/mcp-time.svg)](https://pkg.go.dev/github.com/TheoBrigitte/mcp-time)
10[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/TheoBrigitte/mcp-time)](https://archestra.ai/mcp-catalog/theobrigitte__mcp-time)
11[![NPM Package](https://img.shields.io/npm/v/@theo.foobar/mcp-time?color)](https://www.npmjs.com/package/@theo.foobar/mcp-time)
12[![Docker Image](https://img.shields.io/docker/v/theo01/mcp-time?label=docker)](https://hub.docker.com/r/theo01/mcp-time)
13 
14<strong>Time MCP Server</strong>
15 
16*A Model Context Protocol server that enables AI assistants to interact with time*
17 
18</div>
19 
20## Overview
21 
22The Time MCP Server is a [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) 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.
23 
24## Features
25 
26- **⏰ Time Manipulation** - Get current time, convert between timezones, and add or subtract durations
27- **🗣️ Natural Language Parsing** - Understands relative time expressions like "yesterday" or "next month"
28- **⚖️ Time Comparison** - Compare two different times with ease
29- **🎨 Flexible Formatting** - Supports a wide variety of predefined and custom time formats
30- **✅ MCP Compliance** - Fully compatible with the Model Context Protocol standard
31- **🔄 Multiple Transports** - Supports `stdio` for local integrations and `HTTP stream` for network access
32 
33## Installation
34 
35This MCP server can be integrated with various AI assistant clients that support the Model Context Protocol, including [Cursor](https://cursor.com/), [Claude Desktop](https://claude.ai/download), [Claude Code](https://www.claude.com/product/claude-code), and [many more](https://modelcontextprotocol.io/clients).
36 
37### 🚀 One-Click Install (Cursor)
38 
39Click the button below to automatically configure the MCP server using Docker in your [Cursor](https://cursor.com) environment:
40 
41<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=time&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItLXJtIiwiLWkiLCJ0aGVvMDEvbWNwLXRpbWU6bGF0ZXN0Il19">
42<picture>
43  <source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/deeplink/mcp-install-dark.svg">
44  <source media="(prefers-color-scheme: light)" srcset="https://cursor.com/deeplink/mcp-install-light.svg">
45  <img alt="Add to Cursor" src="https://cursor.com/deeplink/mcp-install-light.svg" width="200">
46</picture>
47</a>
48 
49### Using npx (JavaScript/Node.js)
50 
51This method runs the MCP server using [`npx`](https://docs.npmjs.com/cli/v8/commands/npx), which requires Node.js to be installed. Copy the following JSON configuration into your MCP client settings:
52 
53```json
54{
55  "mcpServers": {
56    "mcp-time": {
57      "type": "stdio",
58      "command": "npx",
59      "args": [
60        "-y",
61        "@theo.foobar/mcp-time"
62      ]
63    }
64  }
65}
66```
67 
68### Using Docker
69 
70Run the MCP server in an isolated container. Requires [Docker](https://www.docker.com/get-started/) to be installed. Copy this JSON configuration into your MCP client settings:
71 
72```json
73{
74  "mcpServers": {
75    "mcp-time": {
76      "type": "stdio",
77      "command": "docker",
78      "args": [
79        "run",
80        "--rm",
81        "-i",
82        "theo01/mcp-time:latest"
83      ]
84    }
85  }
86}
87```
88 
89### Using binary
90 
91Install 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:
92 
93```json
94{
95  "mcpServers": {
96    "mcp-time": {
97      "type": "stdio",
98      "command": "mcp-time"
99    }
100  }
101}
102```
103 
104#### Option 1: Download from Releases
105 
106Download the latest pre-built binary from the [releases page](https://github.com/TheoBrigitte/mcp-time/releases):
107 
108```bash
109# Replace OS-ARCH with your platform (e.g., linux-amd64, darwin-arm64, windows-amd64)
110curl -Lo mcp-time https://github.com/TheoBrigitte/mcp-time/releases/latest/download/mcp-time.OS-ARCH
111install -D -m 755 ./mcp-time ~/.local/bin/mcp-time
112```
113 
114#### Option 2: Install with Go
115 
116For Go developers, install directly using `go install`:
117 
118```bash
119go install github.com/TheoBrigitte/mcp-time/cmd/mcp-time@latest
120```
121 
122The binary will be installed in your `$GOPATH/bin` directory.
123 
124#### Option 3: Build from Source
125 
126Clone and build the project using `make`:
127 
128```bash
129git clone https://github.com/TheoBrigitte/mcp-time.git
130cd mcp-time
131make install
132```
133 
134The binary will be installed in `~/.local/bin/mcp-time`.
135 
136## Usage
137 
138### Basic Usage
139 
140**Start with stdio transport** (default, for MCP clients):
141```bash
142mcp-time
143```
144 
145**Start with HTTP stream transport** (for network access):
146```bash
147mcp-time --transport stream --address "http://localhost:8080/mcp"
148```
149 
150### Command-Line Options
151 
152The server supports the following flags for advanced configurations:
153 
154```
155$ mcp-time --help
156An MCP (Model Context Protocol) server which provides utilities to work with time and dates.
157 
158Usage:
159  mcp-time [flags]
160 
161Flags:
162      --address string     Listen address for Stream HTTP Server (only for --transport stream) (default "http://localhost:8080/mcp")
163  -h, --help               help for mcp-time
164      --log-file string    Path to log file (logs is disabled if not specified)
165  -t, --transport string   Transport layer: stdio, stream. (default "stdio")
166      --version            Print version information and exit
167```
168 
169## Available Tools
170 
171### `current_time`
172 
173Get the current time in any timezone and format.
174 
175**Parameters:**
176- `format` (optional) - The output format (predefined like `RFC3339`, `Kitchen`, or custom Go layout)
177- `timezone` (optional) - Target timezone in IANA format (e.g., `America/New_York`). Defaults to UTC
178 
179**Example:** "What time is it in Tokyo?"
180 
181### `relative_time`
182 
183Get a time based on a relative natural language expression.
184 
185**Parameters:**
186- `text` (required) - Natural language expression (e.g., `yesterday`, `5 minutes ago`, `next month`)
187- `time` (optional) - Reference time for the expression. Defaults to current time
188- `timezone` (optional) - Target timezone for the output
189- `format` (optional) - Output format for the time
190 
191**Example:** "What was the date 3 weeks ago?"
192 
193### `convert_timezone`
194 
195Convert a given time between timezones.
196 
197**Parameters:**
198- `time` (required) - Input time string (supports various formats)
199- `input_timezone` (optional) - Timezone of the input time
200- `output_timezone` (optional) - Target timezone for the output
201- `format` (optional) - Output format for the time
202 
203**Example:** "Convert 2:30 PM EST to Tokyo time"
204 
205### `add_time`
206 
207Add or subtract a duration from a given time.
208 
209**Parameters:**
210- `time` (required) - Input time string
211- `duration` (required) - Duration to add/subtract (e.g., `2h30m`, `-1h`, `24h`)
212- `timezone` (optional) - Target timezone for the output
213- `format` (optional) - Output format for the time
214 
215**Example:** "What time will it be in 45 minutes?"
216 
217### `compare_time`
218 
219Compare two times and determine their relationship. Supports timezone-aware comparisons.
220 
221**Parameters:**
222- `time_a` (required) - First time to compare
223- `time_a_timezone` (optional) - Timezone for `time_a` in IANA format (e.g., `America/New_York`)
224- `time_b` (required) - Second time to compare
225- `time_b_timezone` (optional) - Timezone for `time_b` in IANA format (e.g., `Europe/London`)
226 
227**Returns:**
228- `-1` if `time_a` is before `time_b`
229- `0` if `time_a` equals `time_b`
230- `1` if `time_a` is after `time_b`
231 
232**Example:** "Is 3 PM EST before 8 PM GMT?"
233 
234## Contributing
235 
236Contributions 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.
237 
238## License
239 
240This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
241 
242## Credits
243 
244Built with these excellent libraries:
245- [araddon/dateparse](https://github.com/araddon/dateparse) - Parse dates without knowing the format
246- [tj/go-naturaldate](https://github.com/tj/go-naturaldate) - Natural language date parsing
247- [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) - Model Context Protocol SDK for Go
248