1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
|
# Time MCP Server
A Model Context Protocol (MCP) server that provides comprehensive time and date utilities for AI assistants.
## Overview
The Time MCP server enables AI assistants to work with time-related operations through a standardized protocol. It provides tools for getting current time, converting between time zones, parsing dates, and performing time calculations.
## Installation
### From Source
```bash
# Build the binary
make time
# Install system-wide (requires sudo)
sudo make install
```
### Direct Build
```bash
go build -o mcp-time ./cmd/time
```
## Usage
### Command Line Arguments
```bash
mcp-time
```
**No arguments required** - The server provides time utilities without any configuration.
### Examples
#### Basic Testing
```bash
# Test server initialization
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | timeout 5s mcp-time
# List available tools
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | timeout 5s mcp-time
# Get current time
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {}}}' | timeout 5s mcp-time
```
#### Time Operations Testing
```bash
# Get current time in specific timezone
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "America/New_York"}}}' | timeout 5s mcp-time
# Convert time between timezones
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T15:30:00Z", "from_timezone": "UTC", "to_timezone": "America/Los_Angeles"}}}' | timeout 5s mcp-time
# Get current time in multiple formats
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"format": "RFC3339"}}}' | timeout 5s mcp-time
```
## Available Tools
### Current Time
- **`get_current_time`**: Get current date and time
- **Parameters:**
- `timezone` (optional): Target timezone (e.g., "America/New_York", "Europe/London")
- `format` (optional): Output format ("RFC3339", "Unix", "ISO8601", "Human")
- **Returns:** Current time in specified timezone and format
### Time Conversion
- **`convert_time`**: Convert time between different timezones and formats
- **Parameters:**
- `time` (required): Input time string or Unix timestamp
- `from_timezone` (optional): Source timezone (defaults to UTC)
- `to_timezone` (required): Target timezone
- `format` (optional): Output format
- **Returns:** Converted time in target timezone and format
## Supported Timezones
### Major Timezones
- **UTC**: Coordinated Universal Time
- **America/New_York**: Eastern Time (US & Canada)
- **America/Chicago**: Central Time (US & Canada)
- **America/Denver**: Mountain Time (US & Canada)
- **America/Los_Angeles**: Pacific Time (US & Canada)
- **Europe/London**: Greenwich Mean Time / British Summer Time
- **Europe/Paris**: Central European Time
- **Europe/Berlin**: Central European Time
- **Asia/Tokyo**: Japan Standard Time
- **Asia/Shanghai**: China Standard Time
- **Asia/Kolkata**: India Standard Time
- **Australia/Sydney**: Australian Eastern Time
### Full IANA Support
The server supports all IANA timezone identifiers. Common patterns:
- **Continent/City**: `America/New_York`, `Europe/London`, `Asia/Tokyo`
- **Regional**: `US/Eastern`, `US/Pacific`, `GMT`, `UTC`
## Supported Formats
### Input Formats
- **RFC3339**: `2023-12-01T15:30:00Z`
- **ISO8601**: `2023-12-01T15:30:00+00:00`
- **Unix Timestamp**: `1701439800` (seconds since epoch)
- **Human Readable**: `December 1, 2023 3:30 PM`
### Output Formats
- **RFC3339**: `2023-12-01T15:30:00Z`
- **ISO8601**: `2023-12-01T15:30:00-08:00`
- **Unix**: `1701439800`
- **Human**: `Friday, December 1, 2023 at 3:30 PM PST`
## Configuration Examples
### Claude Desktop Integration
```json
{
"mcpServers": {
"time": {
"command": "/usr/local/bin/mcp-time"
}
}
}
```
### Multiple Time Services
```json
{
"mcpServers": {
"time-utils": {
"command": "/usr/local/bin/mcp-time"
}
}
}
```
## Example Workflows
### Current Time Operations
```bash
# Get current UTC time
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {}}}' | mcp-time
# Get current time in New York
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "America/New_York"}}}' | mcp-time
# Get current time in multiple formats
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "Europe/London", "format": "Human"}}}' | mcp-time
# Get Unix timestamp
echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"format": "Unix"}}}' | mcp-time
```
### Time Zone Conversions
```bash
# Convert UTC to Eastern Time
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T20:30:00Z", "from_timezone": "UTC", "to_timezone": "America/New_York"}}}' | mcp-time
# Convert Eastern to Pacific Time
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T15:30:00", "from_timezone": "America/New_York", "to_timezone": "America/Los_Angeles"}}}' | mcp-time
# Convert to multiple timezones
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T12:00:00Z", "to_timezone": "Asia/Tokyo", "format": "Human"}}}' | mcp-time
```
### Business Hours Calculations
```bash
# Check if it's business hours in New York
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "America/New_York", "format": "Human"}}}' | mcp-time
# Get meeting time across timezones
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T14:00:00", "from_timezone": "America/New_York", "to_timezone": "Europe/London"}}}' | mcp-time
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T14:00:00", "from_timezone": "America/New_York", "to_timezone": "Asia/Tokyo"}}}' | mcp-time
```
### Unix Timestamp Operations
```bash
# Convert Unix timestamp to human readable
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "1701439800", "to_timezone": "America/Los_Angeles", "format": "Human"}}}' | mcp-time
# Get current Unix timestamp
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"format": "Unix"}}}' | mcp-time
```
## Advanced Features
### Automatic Format Detection
- **Smart Parsing**: Automatically detects input time format
- **Flexible Input**: Accepts various common time formats
- **Error Handling**: Clear error messages for invalid formats
### Daylight Saving Time
- **Automatic DST**: Handles daylight saving time transitions
- **Historical Accuracy**: Correct DST rules for historical dates
- **Future Dates**: Accurate predictions for future DST changes
### High Precision
- **Nanosecond Precision**: Full Go time precision support
- **Leap Seconds**: Proper handling of leap seconds
- **Time Zones**: Complete IANA timezone database support
## Use Cases
### Scheduling and Coordination
```bash
# Plan international meeting
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-05T09:00:00", "from_timezone": "America/New_York", "to_timezone": "Europe/London"}}}' | mcp-time
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-05T09:00:00", "from_timezone": "America/New_York", "to_timezone": "Asia/Tokyo"}}}' | mcp-time
```
### Log Analysis
```bash
# Convert log timestamps
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "1701439800", "to_timezone": "America/Denver", "format": "Human"}}}' | mcp-time
```
### Business Operations
```bash
# Check current time in office locations
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "America/New_York", "format": "Human"}}}' | mcp-time
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "Europe/London", "format": "Human"}}}' | mcp-time
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "Asia/Singapore", "format": "Human"}}}' | mcp-time
```
## Performance
- **Startup Time**: ~1ms
- **Memory Usage**: <5MB
- **Response Time**: <1ms for time operations
- **Timezone Data**: Built-in IANA timezone database
## Troubleshooting
### Common Issues
1. **"Invalid timezone" errors**
```bash
# Check valid timezone format
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "UTC"}}}' | mcp-time
# Use IANA format: Continent/City
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"timezone": "America/New_York"}}}' | mcp-time
```
2. **"Invalid time format" errors**
```bash
# Use RFC3339 format for reliability
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-12-01T15:30:00Z", "to_timezone": "UTC"}}}' | mcp-time
# Or Unix timestamp
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "1701439800", "to_timezone": "UTC"}}}' | mcp-time
```
### Testing Time Operations
```bash
# Test basic functionality
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {}}}' | mcp-time
# Test timezone conversion
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "convert_time", "arguments": {"time": "2023-01-01T00:00:00Z", "to_timezone": "America/New_York"}}}' | mcp-time
# Test format conversion
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {"format": "Unix"}}}' | mcp-time
```
## Best Practices
1. **Use IANA Timezones**: Always use standard IANA timezone identifiers
2. **Specify Formats**: Explicitly specify input/output formats when possible
3. **Handle DST**: Be aware of daylight saving time transitions
4. **UTC for Storage**: Store times in UTC and convert for display
5. **Validate Inputs**: Check timezone and format validity before processing
## Timezone Reference
### Common US Timezones
- `America/New_York` (EST/EDT)
- `America/Chicago` (CST/CDT)
- `America/Denver` (MST/MDT)
- `America/Los_Angeles` (PST/PDT)
- `America/Anchorage` (AKST/AKDT)
- `Pacific/Honolulu` (HST)
### Common European Timezones
- `Europe/London` (GMT/BST)
- `Europe/Paris` (CET/CEST)
- `Europe/Berlin` (CET/CEST)
- `Europe/Rome` (CET/CEST)
- `Europe/Madrid` (CET/CEST)
### Common Asian Timezones
- `Asia/Tokyo` (JST)
- `Asia/Shanghai` (CST)
- `Asia/Kolkata` (IST)
- `Asia/Dubai` (GST)
- `Asia/Singapore` (SGT)
## Contributing
See the main project README for contribution guidelines.
## License
This project is licensed under the same terms as the parent MCP project.
|
