@cicatriz/timezone-toolkit
Advanced tools
Advanced MCP server providing comprehensive time and timezone tools
An advanced MCP (Model Context Protocol) server providing comprehensive time and timezone tools with enhanced features beyond basic conversion.
| 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 |
To run the TimezoneToolkit MCP server using Node.js npx, use the following command:
npx -y @cicatriz/timezone-toolkit@latest
To add this server to Cursor IDE:
.cursor/mcp.json file:{
"mcpServers": {
"timezone-toolkit": {
"command": "npx",
"args": [
"-y",
"@cicatriz/timezone-toolkit"
]
}
}
}
See the Cursor documentation for more details.
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"
]
}
}
}
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"
]
}
}
}
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"
]
}
}
}
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.
You can also run it as CLI by running the following command:
npx -y @cicatriz/timezone-toolkit@latest
# Install globally from npm
npm install -g @cicatriz/timezone-toolkit
# Run the server
timezone-toolkit
# 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
After installation, you can use TimezoneToolkit with Claude Desktop:
TimezoneToolkit also provides a RESTful API for accessing its functionality without Claude Desktop:
# Using npm
npm install -g @cicatriz/timezone-toolkit
node server.js
The API server will be available at http://localhost:3000
GET /api/tools - List all available toolsPOST /api/convert-time - Convert time between timezonesPOST /api/current-time - Get current time in a timezonePOST /api/sunrise-sunset - Calculate sunrise/sunset timesPOST /api/moon-phase - Calculate moon phasePOST /api/timezone-difference - Calculate timezone differencePOST /api/list-timezones - List available timezonesPOST /api/countdown - Calculate countdown to a datePOST /api/business-days - Calculate business days between datesPOST /api/format-date - Format a dateFor detailed API documentation, see the API README.
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"
}
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"
}
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.Example:
{
"date": "2023-06-21",
"latitude": 37.7749,
"longitude": -122.4194,
"timezone": "America/Los_Angeles"
}
Response:
{
"date": "2023-06-21",
"sunrise": "05:48:11 AM",
"sunset": "08:35:13 PM",
"civilTwilight": {
"dawn": "05:17:22 AM",
"dusk": "09:06:02 PM"
},
"nauticalTwilight": {
"dawn": "04:38:43 AM",
"dusk": "09:44:41 PM"
},
"astronomicalTwilight": {
"dawn": "03:52:50 AM",
"dusk": "10:30:34 PM"
},
"dayLength": "14 hours 47 minutes",
"timezone": "America/Los_Angeles"
}
Calculates moon phase for a specific date.
Parameters:
date (optional): Date for calculation (ISO string or natural language). Defaults to current date.timezone (optional): IANA timezone name (e.g., 'Europe/Paris'). Defaults to UTC.Example:
{
"date": "2023-01-06",
"timezone": "UTC"
}
Response:
{
"date": "2023-01-06",
"phase": 0.998,
"phaseName": "Full Moon",
"illumination": 0.997,
"timezone": "UTC"
}
Calculates the time difference between two timezones.
Parameters:
fromTimezone: Source IANA timezone name (e.g., 'America/New_York')toTimezone: Target IANA timezone name (e.g., 'Europe/London')Example:
{
"fromTimezone": "America/New_York",
"toTimezone": "Asia/Tokyo"
}
Response:
{
"fromTimezone": "America/New_York",
"toTimezone": "Asia/Tokyo",
"timeDifference": "+14 hours",
"currentTimeFrom": "3/25/2025, 6:15 PM",
"currentTimeTo": "3/26/2025, 8:15 AM",
"hoursDifference": 14,
"minutesDifference": 0,
"totalMinutesDifference": 840,
"direction": "ahead"
}
Lists available IANA timezones, optionally filtered by region.
Parameters:
region (optional): Filter timezones by region (e.g., 'America', 'Europe', 'Asia')Example:
{
"region": "Europe"
}
Response:
{
"timezones": [
{
"timezone": "Europe/Amsterdam",
"currentTime": "3/25/2025, 11:15 PM",
"offset": "+02:00"
},
{
"timezone": "Europe/Berlin",
"currentTime": "3/25/2025, 11:15 PM",
"offset": "+02:00"
},
// Additional European timezones...
],
"count": 7,
"region": "Europe"
}
Calculates time remaining until a specific date/event.
Parameters:
targetDate: Target date/time (ISO string or natural language)timezone (optional): IANA timezone name (e.g., 'America/New_York'). Defaults to system timezone.title (optional): Title or name of the eventExample:
{
"targetDate": "2025-12-31T23:59:59",
"timezone": "UTC",
"title": "New Year's Eve"
}
Response:
{
"title": "New Year's Eve",
"targetDate": "2025-12-31T23:59:59.000Z",
"formattedTargetDate": "Wednesday, December 31, 2025, 11:59:59 PM GMT",
"currentDate": "2025-03-25T18:15:30.000Z",
"timezone": "UTC",
"isPast": false,
"countdown": "9 months, 6 days, 5 hours, 44 minutes, 29 seconds",
"remaining": {
"years": 0,
"months": 9,
"days": 6,
"hours": 5,
"minutes": 44,
"seconds": 29,
"totalDays": 281,
"totalHours": 6749,
"totalMinutes": 404969,
"totalSeconds": 24298169
}
}
Calculates business days between two dates (excluding weekends).
Parameters:
startDate: Start date (ISO string or natural language)endDate: End date (ISO string or natural language)timezone (optional): IANA timezone name (e.g., 'America/New_York'). Defaults to system timezone.excludeHolidays (optional): Whether to exclude common holidays (US holidays only). Defaults to false.Example:
{
"startDate": "2023-05-01",
"endDate": "2023-05-31",
"timezone": "UTC",
"excludeHolidays": true
}
Response:
{
"startDate": "2023-05-01",
"endDate": "2023-05-31",
"businessDays": 22,
"calendarDays": 31,
"weekendDays": 8,
"holidaysExcluded": 1,
"timezone": "UTC",
"businessDatesIncluded": ["2023-05-01", "2023-05-02", "2023-05-03", "2023-05-04", "2023-05-05", "2023-05-08", "2023-05-09", "2023-05-10", "2023-05-11", "2023-05-12", "2023-05-15", "2023-05-16", "2023-05-17", "2023-05-18", "2023-05-19", "2023-05-22", "2023-05-23", "2023-05-24", "2023-05-25", "2023-05-26", "2023-05-30", "2023-05-31"]
}
Formats a date in various styles.
Parameters:
date: Date to format (ISO string or natural language). Defaults to current date.timezone (optional): IANA timezone name (e.g., 'America/New_York'). Defaults to system timezone.format (optional): Output format ('short', 'medium', 'full', 'iso', 'relative'). Defaults to 'medium'.locale (optional): Locale for formatting (e.g., 'en-US', 'fr', 'de'). Defaults to 'en-US'.Example:
{
"date": "2023-12-25",
"timezone": "Europe/Paris",
"format": "full",
"locale": "fr"
}
Response:
{
"originalDate": "2023-12-25",
"parsedDate": "2023-12-25T00:00:00.000+01:00",
"formattedDate": "lundi 25 décembre 2023",
"formattedTime": "00:00:00 heure normale d'Europe centrale",
"formattedDateTime": "lundi 25 décembre 2023 à 00:00:00 heure normale d'Europe centrale",
"dayOfWeek": "lundi",
"dayOfMonth": 25,
"month": "décembre",
"year": 2023,
"timezone": "Europe/Paris",
"locale": "fr",
"format": "full"
}
TimezoneToolkit is built using the Model Context Protocol (MCP) specification, which allows it to integrate seamlessly with Claude Desktop. The server is implemented in TypeScript and uses the following architecture:
Contributions are welcome! Please feel free to submit a Pull Request.
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)TimezoneToolkit includes a comprehensive test script that can be used to verify the functionality of the MCP server. The test script can be used to test the local build, the version flag, list all available tools, test specific tools, and test the npm package after publishing.
# Test the local build (default)
node test-server.js
# Test a specific tool
node test-server.js --tool=calculate_sunrise_sunset
# List all available tools
node test-server.js --list
# Test the version flag
node test-server.js --test-version
# Test the published npm package (after publishing)
node test-server.js --npm
The test script will output detailed information about the test results, including whether the response format is correct and whether the content is valid JSON.
Testing local build...
Running: node /path/to/timezone-toolkit/dist/index.js
Sending request: {
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_current_time",
"arguments": {
"timezone": "America/New_York"
}
}
}
Response: {
"result": {
"content": [
{
"type": "text",
"text": "{\n \"currentTime\": \"Mar 25, 2025, 9:54 PM\",\n \"timezone\": \"America/New_York\",\n \"utcOffset\": \"-04:00\"\n}"
}
]
},
"jsonrpc": "2.0",
"id": 1
}
✅ Response format is correct (has content array)
✅ Content is valid JSON: {
currentTime: 'Mar 25, 2025, 9:54 PM',
timezone: 'America/New_York',
utcOffset: '-04:00'
}
✅ Test completed successfully!
Tool not showing up in Claude Desktop
Incorrect timezone calculations
Sunrise/sunset calculations not working
TimezoneToolkit processes all data locally and does not send any information to external servers. Your timezone data and queries remain private on your device.
ISC
Cicatriz (thedawg100@gmail.com)
FAQs
Advanced MCP server providing comprehensive time and timezone tools
The npm package @cicatriz/timezone-toolkit receives a total of 38 weekly downloads. As such, @cicatriz/timezone-toolkit popularity was classified as not popular.
We found that @cicatriz/timezone-toolkit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Four npm packages disguised as cryptographic tools steal developer credentials and send them to attacker-controlled Telegram infrastructure.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.