Time Node MCP Server
A 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.
Features
- Accurate timezone handling - Get current time in any IANA timezone
- Time conversion - Convert time between different timezones
- Multiple formats - ISO 8601, localized, and human-readable formats
- System timezone detection - Automatically detect system timezone
- DST awareness - Correctly handles Daylight Saving Time transitions
- Date utilities - Get current date with day-of-week information
Installation
Prerequisites
- Node.js 18.0.0 or higher
- npm or yarn
Install and Build
# Clone or download the project
cd time-node-mcp
# Install dependencies
npm install
# Build the TypeScript code
npm run build
Usage with Claude Desktop
Add the following configuration to your Claude Desktop settings file:
macOS
~/Library/Application Support/Claude/claude_desktop_config.json
Windows
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"time-node-mcp": {
"command": "node",
"args": ["/path/to/time-node-mcp/dist/index.js"]
}
}
}
Replace /path/to/time-node-mcp/ with the actual path to your installation directory.
Available Tools
1. get_current_time
Get the current date and time in a specific timezone.
Parameters:
timezone(required): IANA timezone identifier (e.g., "America/New_York", "Europe/London")format(optional): Output format - "iso", "local", or "full" (default: "iso")
Example:
{
"timezone": "America/New_York",
"format": "full"
}
2. convert_time
Convert time from one timezone to another.
Parameters:
sourceTimezone(required): Source IANA timezone identifiertargetTimezone(required): Target IANA timezone identifiertime(required): Time in HH:MM or HH:MM:SS format (24-hour)date(optional): Date in YYYY-MM-DD format (uses current date if not provided)
Example:
{
"sourceTimezone": "America/New_York",
"targetTimezone": "Europe/London",
"time": "14:30",
"date": "2024-08-12"
}
3. get_system_timezone
Get the system's current timezone with current time information.
Parameters: None
4. get_current_date
Get the current date in a specific timezone with day-of-week information.
Parameters:
timezone(required): IANA timezone identifierincludeTime(optional): Whether to include time information (default: false)
Example:
{
"timezone": "Asia/Tokyo",
"includeTime": true
}
Development
Scripts
# Build the project
npm run build
# Build and watch for changes
npm run dev
# Run the server directly (after building)
npm start
# Lint the code
npm run lint
# Type check
npm run typecheck
Project Structure
time-node-mcp/
├── src/
│ ├── index.ts # Main MCP server implementation
│ ├── time-service.ts # Core time/timezone functionality
│ └── interfaces.ts # TypeScript interfaces
├── dist/ # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md
Common Use Cases
- Correct current date/time: When Claude needs to know "what day is today" in your timezone
- Meeting scheduling: Convert meeting times between different timezones
- Travel planning: Understand time differences when traveling
- International coordination: Work with teams across multiple timezones
Timezone Support
This server supports all IANA timezone identifiers, including:
America/New_YorkEurope/LondonAsia/TokyoAustralia/SydneyPacific/Auckland- And many more...
You can find a complete list of supported timezones at: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
Error Handling
The server provides comprehensive error handling for:
- Invalid timezone identifiers
- Malformed time formats
- Invalid date formats
- System errors
All errors are returned in a structured JSON format with descriptive messages.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and linting
- Submit a pull request
License
MIT License - see LICENSE file for details.
Troubleshooting
Common Issues
"Invalid timezone" error:
- Ensure you're using valid IANA timezone identifiers
- Check spelling and capitalization (e.g., "America/New_York", not "america/new_york")
MCP server not connecting:
- Verify the path in your Claude Desktop configuration is correct
- Ensure the project is built (
npm run build) - Check that Node.js is installed and accessible
Date/time seems incorrect:
- The server uses your system's current date/time as the base
- Ensure your system clock is correct and timezone is properly set