time-node-mcp

Purpose

time-node-mcp is a Model Context Protocol (MCP) server dedicated to providing timezone-aware date and time operations. The core problem it solves is: AI assistants often return incorrect date information due to timezone confusion. Through this server, AI assistants can obtain accurate date and time data based on a specified timezone.

Main Capabilities

• Accurate timezone handling: Get the current time in any IANA timezone.
• Time conversion: Convert time between different timezones.
• Multiple formats: Supports ISO 8601, localized, and human-readable formats.
• System timezone detection: Automatically detects the system timezone.
• Daylight saving time awareness: Correctly handles daylight saving time (DST) transitions.
• Date utilities: Get the current date and corresponding weekday information.

Available Tools

The server provides four tools:

1. get_current_time: Get the current date and time in a specified timezone.

   • timezone(required): IANA timezone identifier (for example "America/New_York", "Europe/London").
   • format(optional): Output format, can be "iso", "local", or "full", default "iso".

2. convert_time: Convert time from one timezone to another timezone.

   • sourceTimezone(required): Source IANA timezone identifier.
   • targetTimezone(required): Target IANA timezone identifier.
   • time(required): HH:MM or HH:MM:SS format (24-hour clock).
   • date(optional): YYYY-MM-DD format; uses the current date when not provided.

3. get_system_timezone: Get the system's current timezone and current time information. No parameters.

4. get_current_date: Get the current date and weekday information in a specified timezone.

   • timezone(required): IANA timezone identifier.
   • includeTime(optional): Whether to include time information, default false.

Usage

Environment Requirements

• Node.js 18.0.0 or later.

Installation and Build

The materials provide installation and build steps, but the specific commands are not fully listed in the provided content. Usually you need to clone the repository and run npm run build.

Using with Claude Desktop

Add the following configuration to Claude Desktop's settings file:

• macOS:~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

You need to replace /path/to/time-node-mcp/ with the path of the actual installation directory.

Applicable Scenarios

• Accurate current date/time: When Claude needs to know "what day it is today" in the user's timezone.
• Meeting scheduling: Convert meeting times between different timezones.
• Travel planning: Understand time differences while traveling.
• International collaboration: Work with teams across multiple timezones.

Timezone Support

The server supports all IANA timezone identifiers, including but not limited to:

• America/New_York
• Australia/Sydney
• Pacific/Auckland

The complete list can be found in the IANA timezone database.

Error Handling

The server provides comprehensive error handling for the following situations and returns descriptive error information in structured JSON format:

• Invalid timezone identifiers
• Incorrectly formatted time formats
• Invalid date formats

Limitations and Notes

• Requires Node.js 18.0.0 or later.
• The server uses the system's current date/time as the baseline, so you need to ensure the system clock is correct and the timezone settings are accurate.
• Use valid IANA timezone identifiers and pay attention to case (for example "America/New_York" rather than "america/new_york").
• If the MCP server cannot connect, verify whether the path in the Claude Desktop configuration is correct, and ensure the project has been built (npm run build) and Node.js is installed and accessible.
• Licensed under the MIT License.