<div align="center">

<h1>TimezoneToolkit MCP Server</h1>
<p>An advanced MCP (Model Context Protocol) server providing comprehensive time and timezone tools with enhanced features beyond basic conversion.</p>
</div>

Available Tools

| Tool | Description |
| ---- | ----------- |
| convert_time | Convert a time from one timezone to another |
| get_current_time | Get the current time in a specified timezone |
| calculate_sunrise_sunset | Calculate sunrise, sunset, and twilight times for a specific location and date |
| calculate_moon_phase | Calculate moon phase for a specific date |
| calculate_timezone_difference | Calculate the time difference between two timezones |
| list_timezones | List available IANA timezones, optionally filtered by region |
| calculate_countdown | Calculate time remaining until a specific date/event |
| calculate_business_days | Calculate business days between two dates (excluding weekends) |
| format_date | Format a date in various styles |

🌟 Features

🕒 Basic Timezone Conversion

- Convert times between any IANA timezone - Get current time in any timezone - Format time in various styles (short, medium, full) - Calculate time differences in hours/minutes - List available IANA timezones

🌅 Sunrise/Sunset and Astronomical Calculations

- Calculate sunrise and sunset times for any location - Include twilight times (civil, nautical, astronomical) - Calculate day length for any location/date - Calculate moon phases for any date

📅 Date and Time Utilities

- Format dates in various styles (short, medium, full, ISO, relative) - Calculate business days between dates - Create countdown timers to future events - Support for multiple locales and timezones

💻 Installation

Prerequisites

- Node.js 18.x or higher - The TimezoneToolkit MCP server requires Node.js 18+ to run properly.

Setup

To run the TimezoneToolkit MCP server using Node.js npx, use the following command:

npx -y @cicatriz/timezone-toolkit@latest

Client-Specific Installation

Cursor

To add this server to Cursor IDE:

1. Go to Cursor Settings > MCP
2. Click + Add new Global MCP Server
3. Add the following configuration to your global .cursor/mcp.json file:

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

See the Cursor documentation for more details.

Windsurf

To set up MCP with Cascade, navigate to Windsurf - Settings > Advanced Settings or Command Palette > Open Windsurf Settings Page.

Scroll down to the Cascade section and add the TimezoneToolkit MCP server directly in mcp_config.json:

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

Cline

Add the following JSON manually to your cline_mcp_settings.json via Cline MCP Server setting:

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

Roo Code

Access the MCP settings by clicking Edit MCP Settings in Roo Code settings or using the Roo Code: Open MCP Config command in VS Code's command palette:

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

Claude

Add the following to your claude_desktop_config.json file:

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

See the Claude Desktop documentation for more details.

CLI

You can also run it as CLI by running the following command:

npx -y @cicatriz/timezone-toolkit@latest

Alternative Installation Methods

Install from npm

# Install globally from npm
npm install -g @cicatriz/timezone-toolkit
Run the server
timezone-toolkit

Manual Installation

# Clone the repository
git clone https://github.com/Cicatriiz/timezone-toolkit.git
cd timezone-toolkit
Install dependencies
npm install
Build the project
npm run build
Run the server
node dist/index.js

💬 Usage with Claude Desktop

After installation, you can use TimezoneToolkit with Claude Desktop:

1. Open Claude Desktop
2. Start a new conversation
3. Click the hammer icon to see available tools
4. Select any of the TimezoneToolkit tools

🔗 API Access

TimezoneToolkit also provides a RESTful API for accessing its functionality without Claude Desktop:

Starting the API Server

# Using npm
npm install -g @cicatriz/timezone-toolkit
node server.js

The API server will be available at http://localhost:3000

API Endpoints

- GET /api/tools - List all available tools
- POST /api/convert-time - Convert time between timezones
- POST /api/current-time - Get current time in a timezone
- POST /api/sunrise-sunset - Calculate sunrise/sunset times
- POST /api/moon-phase - Calculate moon phase
- POST /api/timezone-difference - Calculate timezone difference
- POST /api/list-timezones - List available timezones
- POST /api/countdown - Calculate countdown to a date
- POST /api/business-days - Calculate business days between dates
- POST /api/format-date - Format a date

For detailed API documentation, see the API README.

Example Queries

- "What time is it now in Tokyo?"
- "Convert 3:00 PM New York time to London time"
- "What time is sunrise tomorrow in San Francisco?"
- "When is sunset today in Paris?"
- "What's the current moon phase?"
- "What's the time difference between New York and Tokyo?"
- "Show me a list of European timezones"
- "How many business days are there between March 1 and April 15?"
- "Format today's date in French locale"
- "How much time is left until New Year's Eve?"

🔧 Available Tools

1. convert_time

Converts a time from one timezone to another.

Parameters:
- time (optional): Time to convert (ISO string or natural language). Defaults to current time if not provided.
- fromTimezone: Source IANA timezone name (e.g., 'America/New_York')
- toTimezone: Target IANA timezone name (e.g., 'Europe/London')
- format (optional): Output format ('short', 'medium', 'full'). Defaults to 'medium'

Example:

{

  "time": "2023-12-25T14:30:00",

  "fromTimezone": "America/New_York",

  "toTimezone": "Asia/Tokyo",

  "format": "full"

}

Response:

{

  "originalTime": "2023-12-25T14:30:00.000-05:00",

  "convertedTime": "Tuesday, December 26, 2023, 4:30:00 AM Japan Standard Time",

  "fromTimezone": "America/New_York",

  "toTimezone": "Asia/Tokyo",

  "timeDifference": "+14 hours"

}

2. get_current_time

Gets the current time in a specified timezone.

Parameters:
- timezone: IANA timezone name (e.g., 'Asia/Tokyo')
- format (optional): Output format ('short', 'medium', 'full'). Defaults to 'medium'

Example:

{

  "timezone": "Europe/London",

  "format": "full"

}

Response:

{

  "currentTime": "Monday, March 25, 2025, 10:15:30 PM British Summer Time",

  "timezone": "Europe/London",

  "utcOffset": "+01:00"

}

3. calculate_sunrise_sunset

Calculates sunrise, sunset, and twilight times for a specific location and date.

Parameters:
- date (optional): Date for calculation (ISO string or natural language). Defaults to current date.
- latitude: Latitude of the location (-90 to 90)
- longitude: Longitude of the location (-180 to 180)
- timezone (optional): IANA timezone name (e.g., 'Europe/Paris'). Defaults to UTC.

…