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

Related MCP server: date

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 identifier

• targetTimezone (required): Target IANA timezone identifier

• time (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 identifier

• includeTime (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

1. Correct current date/time: When Claude needs to know "what day is today" in your timezone

2. Meeting scheduling: Convert meeting times between different timezones

3. Travel planning: Understand time differences when traveling

4. International coordination: Work with teams across multiple timezones

Timezone Support

This server supports all IANA timezone identifiers, including:

• America/New_York

• Europe/London

• Asia/Tokyo

• Australia/Sydney

• Pacific/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

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Run tests and linting

5. 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