Time Node MCP Server

1# Time Node MCP Server
2 
3A Model Context Protocol (MCP) server that provides timezone-aware date and time operations. This server addresses the common issue where AI assistants provide incorrect date information due to timezone confusion.
4 
5## Features
6 
7- **Accurate timezone handling** - Get current time in any IANA timezone
8- **Time conversion** - Convert time between different timezones
9- **Multiple formats** - ISO 8601, localized, and human-readable formats
10- **System timezone detection** - Automatically detect system timezone
11- **DST awareness** - Correctly handles Daylight Saving Time transitions
12- **Date utilities** - Get current date with day-of-week information
13 
14## Installation
15 
16### Prerequisites
17 
18- Node.js 18.0.0 or higher
19- npm or yarn
20 
21### Install and Build
22 
23```bash
24# Clone or download the project
25cd time-node-mcp
26 
27# Install dependencies
28npm install
29 
30# Build the TypeScript code
31npm run build
32```
33 
34## Usage with Claude Desktop
35 
36Add the following configuration to your Claude Desktop settings file:
37 
38### macOS
39`~/Library/Application Support/Claude/claude_desktop_config.json`
40 
41### Windows
42`%APPDATA%\Claude\claude_desktop_config.json`
43 
44```json
45{
46  "mcpServers": {
47    "time-node-mcp": {
48      "command": "node",
49      "args": ["/path/to/time-node-mcp/dist/index.js"]
50    }
51  }
52}
53```
54 
55Replace `/path/to/time-node-mcp/` with the actual path to your installation directory.
56 
57## Available Tools
58 
59### 1. get_current_time
60Get the current date and time in a specific timezone.
61 
62**Parameters:**
63- `timezone` (required): IANA timezone identifier (e.g., "America/New_York", "Europe/London")
64- `format` (optional): Output format - "iso", "local", or "full" (default: "iso")
65 
66**Example:**
67```json
68{
69  "timezone": "America/New_York",
70  "format": "full"
71}
72```
73 
74### 2. convert_time
75Convert time from one timezone to another.
76 
77**Parameters:**
78- `sourceTimezone` (required): Source IANA timezone identifier
79- `targetTimezone` (required): Target IANA timezone identifier  
80- `time` (required): Time in HH:MM or HH:MM:SS format (24-hour)
81- `date` (optional): Date in YYYY-MM-DD format (uses current date if not provided)
82 
83**Example:**
84```json
85{
86  "sourceTimezone": "America/New_York",
87  "targetTimezone": "Europe/London",
88  "time": "14:30",
89  "date": "2024-08-12"
90}
91```
92 
93### 3. get_system_timezone
94Get the system's current timezone with current time information.
95 
96**Parameters:** None
97 
98### 4. get_current_date
99Get the current date in a specific timezone with day-of-week information.
100 
101**Parameters:**
102- `timezone` (required): IANA timezone identifier
103- `includeTime` (optional): Whether to include time information (default: false)
104 
105**Example:**
106```json
107{
108  "timezone": "Asia/Tokyo",
109  "includeTime": true
110}
111```
112 
113## Development
114 
115### Scripts
116 
117```bash
118# Build the project
119npm run build
120 
121# Build and watch for changes
122npm run dev
123 
124# Run the server directly (after building)
125npm start
126 
127# Lint the code
128npm run lint
129 
130# Type check
131npm run typecheck
132```
133 
134### Project Structure
135 
136```
137time-node-mcp/
138├── src/
139│   ├── index.ts           # Main MCP server implementation
140│   ├── time-service.ts    # Core time/timezone functionality
141│   └── interfaces.ts      # TypeScript interfaces
142├── dist/                  # Compiled JavaScript (generated)
143├── package.json
144├── tsconfig.json
145└── README.md
146```
147 
148## Common Use Cases
149 
1501. **Correct current date/time**: When Claude needs to know "what day is today" in your timezone
1512. **Meeting scheduling**: Convert meeting times between different timezones
1523. **Travel planning**: Understand time differences when traveling
1534. **International coordination**: Work with teams across multiple timezones
154 
155## Timezone Support
156 
157This server supports all IANA timezone identifiers, including:
158 
159- `America/New_York`
160- `Europe/London`
161- `Asia/Tokyo`
162- `Australia/Sydney`
163- `Pacific/Auckland`
164- And many more...
165 
166You can find a complete list of supported timezones at: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
167 
168## Error Handling
169 
170The server provides comprehensive error handling for:
171- Invalid timezone identifiers
172- Malformed time formats
173- Invalid date formats
174- System errors
175 
176All errors are returned in a structured JSON format with descriptive messages.
177 
178## Contributing
179 
1801. Fork the repository
1812. Create a feature branch
1823. Make your changes
1834. Run tests and linting
1845. Submit a pull request
185 
186## License
187 
188MIT License - see LICENSE file for details.
189 
190## Troubleshooting
191 
192### Common Issues
193 
194**"Invalid timezone" error:**
195- Ensure you're using valid IANA timezone identifiers
196- Check spelling and capitalization (e.g., "America/New_York", not "america/new_york")
197 
198**MCP server not connecting:**
199- Verify the path in your Claude Desktop configuration is correct
200- Ensure the project is built (`npm run build`)
201- Check that Node.js is installed and accessible
202 
203**Date/time seems incorrect:**
204- The server uses your system's current date/time as the base
205- Ensure your system clock is correct and timezone is properly set