MCP Time Server Node

A comprehensive Node.js time manipulation server implementing the Model Context Protocol (MCP) for LLMs like Claude. This server provides powerful time-related operations including timezone conversions, date arithmetic, business day calculations, and more.

Features

🌍 Timezone Operations: Convert times between any IANA timezones
⏰ Current Time: Get current time in any timezone with custom formatting
➕➖ Date Arithmetic: Add or subtract time periods from dates
📊 Duration Calculations: Calculate time between dates in various units
💼 Business Days: Calculate business days excluding weekends and holidays
⏱️ Business Hours: Calculate working hours between timestamps with timezone support
🔄 Recurring Events: Find next occurrences of recurring patterns
📝 Flexible Formatting: Format times in relative, calendar, or custom formats
📅 Days Until: Calculate days until any date or event
🚀 High Performance: Response times < 10ms with intelligent caching
🔒 Security Hardened: Input validation, cache key hashing, ESLint security rules
🛡️ Rate Limiting: Configurable rate limits to prevent abuse
✅ Thoroughly Tested: 703+ tests with 100% coverage

Installation

Using npm (recommended)

npm install -g mcp-time-server-node

Using Claude Code (claude mcp add)

Add the server to Claude Code:

# For npm-published version (when available)
claude mcp add mcp-time-server-node

# For local development/testing
claude mcp add tim-server /path/to/mcp-time-server-node/dist/index.js

Using Claude Desktop

Manually add to your claude_desktop_config.json:

{
  "mcpServers": {
    "time-server": {
      "command": "npx",
      "args": ["-y", "mcp-time-server-node"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Local Testing

For testing before npm publish:

# Build the project
make build

# Test directly
echo '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{}}' | node dist/index.js

# Or add to Claude Code for local testing
cd mcp-time-server-node
claude mcp add time-server-local $(pwd)/dist/index.js

Available Tools

1. `get_current_time`

Get the current time in any timezone.

Parameters:

timezone (optional): IANA timezone name (default: "UTC")
format (optional): date-fns format string
include_offset (optional): Include UTC offset (default: true)

Example:

{
  "timezone": "America/New_York",
  "format": "yyyy-MM-dd HH:mm:ss"
}

2. `convert_timezone`

Convert time between timezones.

Parameters:

time (required): Input time in ISO format or parseable string
from_timezone (required): Source IANA timezone
to_timezone (required): Target IANA timezone
format (optional): Output format string

Example:

{
  "time": "2025-01-20T15:00:00Z",
  "from_timezone": "UTC",
  "to_timezone": "Asia/Tokyo"
}

3. `add_time`

Add a duration to a date/time.

Parameters:

time (required): Base time
amount (required): Amount to add
unit (required): Unit ("years", "months", "days", "hours", "minutes", "seconds")
timezone (optional): Timezone for calculation

Example:

{
  "time": "2025-01-20",
  "amount": 3,
  "unit": "days"
}

4. `subtract_time`

Subtract a duration from a date/time.

Parameters:

Same as add_time

5. `calculate_duration`

Calculate the duration between two times.

Parameters:

start_time (required): Start time
end_time (required): End time
unit (optional): Output unit ("auto", "milliseconds", "seconds", "minutes", "hours", "days")
timezone (optional): Timezone for parsing

Example:

{
  "start_time": "2025-01-20T09:00:00",
  "end_time": "2025-01-20T17:30:00"
}

6. `get_business_days`

Calculate business days between dates.

Parameters:

start_date (required): Start date
end_date (required): End date
exclude_weekends (optional): Exclude Saturdays and Sundays (default: true)
holidays (optional): Array of holiday dates in ISO format
timezone (optional): Timezone for calculation

Example:

{
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "holidays": ["2025-01-01", "2025-01-20"]
}

7. `next_occurrence`

Find the next occurrence of a recurring event.

Parameters:

pattern (required): "daily", "weekly", "monthly", or "yearly"
start_from (optional): Start searching from this date (default: now)
day_of_week (optional): For weekly pattern (0-6, where 0 is Sunday)
day_of_month (optional): For monthly pattern (1-31)
time (optional): Time in HH:mm format
timezone (optional): Timezone for calculation

Example:

{
  "pattern": "weekly",
  "day_of_week": 1,
  "time": "09:00"
}

8. `format_time`

Format time in various human-readable formats.

Parameters:

time (required): Time to format
format (required): "relative", "calendar", or "custom"
custom_format (optional): Format string when using "custom" format
timezone (optional): Timezone for display

Example:

{
  "time": "2025-01-20T15:00:00Z",
  "format": "relative"
}

9. `calculate_business_hours`

Calculate business hours between two times.

Parameters:

start_time (required): Start time
end_time (required): End time
business_hours (optional): Business hours definition (default: 9 AM - 5 PM)
- Can be a single object: { start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }
- Or weekly schedule: { 0: null, 1: { start: {...}, end: {...} }, ... } (0=Sunday, 6=Saturday)
timezone (optional): Timezone for calculation
holidays (optional): Array of holiday dates
include_weekends (optional): Include weekends in calculation (default: false)

Example:

{
  "start_time": "2025-01-20T08:00:00",
  "end_time": "2025-01-24T18:00:00",
  "business_hours": {
    "start": { "hour": 9, "minute": 0 },
    "end": { "hour": 17, "minute": 30 }
  },
  "holidays": ["2025-01-22"],
  "timezone": "America/New_York"
}

10. `days_until`

Calculate days until a target date or event.

Parameters:

target_date (required): Target date (ISO string, natural language like "next Christmas", or Unix timestamp)
timezone (optional): Timezone for calculation (default: system timezone)
format_result (optional): Return formatted string instead of number (default: false)

Example:

{
  "target_date": "2025-12-25",
  "timezone": "America/New_York"
}

Environment Variables

NODE_ENV: Set to "production" for production use
RATE_LIMIT: Maximum requests per minute (default: 100)
RATE_LIMIT_WINDOW: Rate limit window in milliseconds (default: 60000)
CACHE_SIZE: Maximum cache entries (default: 10000)
DEFAULT_TIMEZONE: Override system timezone detection (e.g., "America/New_York")
MAX_LISTENERS: Maximum concurrent requests (default: 20, minimum: 10)

Performance

All operations complete in < 10ms (after initial load)
Intelligent caching reduces repeated calculations
Sliding window rate limiting prevents abuse
Memory-efficient implementation

Error Handling

The server returns structured errors with codes:

INVALID_TIMEZONE: Invalid timezone specified
INVALID_DATE_FORMAT: Cannot parse the provided date
INVALID_UNIT: Invalid time unit specified
RATE_LIMIT_EXCEEDED: Too many requests
INVALID_RECURRENCE_PATTERN: Invalid recurrence pattern

Development

Current Status

Refactoring completed

Building from source

git clone https://github.com/pshempel/mcp-time-node.git
cd mcp-time-server-node
make setup    # Install dependencies and build
make test     # Run all tests

Running tests

make test         # Run all tests
make coverage     # Run with coverage report
make test-watch   # Run in watch mode for TDD

# If tests fail unexpectedly:
make test-quick   # Fix Jest issues and run tests
make reset        # Full environment reset

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Author

pshempel

Acknowledgments

Built with:

Model Context Protocol SDK
date-fns for date manipulation
date-fns-tz for timezone support

MCP Time Server Node

Features

🌍 Timezone Operations: Convert times between any IANA timezones
⏰ Current Time: Get current time in any timezone with custom formatting
➕➖ Date Arithmetic: Add or subtract time periods from dates
📊 Duration Calculations: Calculate time between dates in various units
💼 Business Days: Calculate business days excluding weekends and holidays
⏱️ Business Hours: Calculate working hours between timestamps with timezone support
🔄 Recurring Events: Find next occurrences of recurring patterns
📝 Flexible Formatting: Format times in relative, calendar, or custom formats
📅 Days Until: Calculate days until any date or event
🚀 High Performance: Response times < 10ms with intelligent caching
🔒 Security Hardened: Input validation, cache key hashing, ESLint security rules
🛡️ Rate Limiting: Configurable rate limits to prevent abuse
✅ Thoroughly Tested: 703+ tests with 100% coverage

Installation

Using npm (recommended)

npm install -g mcp-time-server-node

Using Claude Code (claude mcp add)

Add the server to Claude Code:

# For npm-published version (when available)
claude mcp add mcp-time-server-node

# For local development/testing
claude mcp add tim-server /path/to/mcp-time-server-node/dist/index.js

Using Claude Desktop

Manually add to your claude_desktop_config.json:

{
  "mcpServers": {
    "time-server": {
      "command": "npx",
      "args": ["-y", "mcp-time-server-node"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Local Testing

For testing before npm publish:

# Build the project
make build

# Test directly
echo '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{}}' | node dist/index.js

# Or add to Claude Code for local testing
cd mcp-time-server-node
claude mcp add time-server-local $(pwd)/dist/index.js

Available Tools

1. `get_current_time`

Get the current time in any timezone.

Parameters:

timezone (optional): IANA timezone name (default: "UTC")
format (optional): date-fns format string
include_offset (optional): Include UTC offset (default: true)

Example:

{
  "timezone": "America/New_York",
  "format": "yyyy-MM-dd HH:mm:ss"
}

2. `convert_timezone`

Convert time between timezones.

Parameters:

time (required): Input time in ISO format or parseable string
from_timezone (required): Source IANA timezone
to_timezone (required): Target IANA timezone
format (optional): Output format string

Example:

{
  "time": "2025-01-20T15:00:00Z",
  "from_timezone": "UTC",
  "to_timezone": "Asia/Tokyo"
}

3. `add_time`

Add a duration to a date/time.

Parameters:

time (required): Base time
amount (required): Amount to add
unit (required): Unit ("years", "months", "days", "hours", "minutes", "seconds")
timezone (optional): Timezone for calculation

Example:

{
  "time": "2025-01-20",
  "amount": 3,
  "unit": "days"
}

4. `subtract_time`

Subtract a duration from a date/time.

Parameters:

Same as add_time

5. `calculate_duration`

Calculate the duration between two times.

Parameters:

start_time (required): Start time
end_time (required): End time
unit (optional): Output unit ("auto", "milliseconds", "seconds", "minutes", "hours", "days")
timezone (optional): Timezone for parsing

Example:

{
  "start_time": "2025-01-20T09:00:00",
  "end_time": "2025-01-20T17:30:00"
}

6. `get_business_days`

Calculate business days between dates.

Parameters:

start_date (required): Start date
end_date (required): End date
exclude_weekends (optional): Exclude Saturdays and Sundays (default: true)
holidays (optional): Array of holiday dates in ISO format
timezone (optional): Timezone for calculation

Example:

{
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "holidays": ["2025-01-01", "2025-01-20"]
}

7. `next_occurrence`

Find the next occurrence of a recurring event.

Parameters:

pattern (required): "daily", "weekly", "monthly", or "yearly"
start_from (optional): Start searching from this date (default: now)
day_of_week (optional): For weekly pattern (0-6, where 0 is Sunday)
day_of_month (optional): For monthly pattern (1-31)
time (optional): Time in HH:mm format
timezone (optional): Timezone for calculation

Example:

{
  "pattern": "weekly",
  "day_of_week": 1,
  "time": "09:00"
}

8. `format_time`

Format time in various human-readable formats.

Parameters:

time (required): Time to format
format (required): "relative", "calendar", or "custom"
custom_format (optional): Format string when using "custom" format
timezone (optional): Timezone for display

Example:

{
  "time": "2025-01-20T15:00:00Z",
  "format": "relative"
}

9. `calculate_business_hours`

Calculate business hours between two times.

Parameters:

start_time (required): Start time
end_time (required): End time
business_hours (optional): Business hours definition (default: 9 AM - 5 PM)
- Can be a single object: { start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }
- Or weekly schedule: { 0: null, 1: { start: {...}, end: {...} }, ... } (0=Sunday, 6=Saturday)
timezone (optional): Timezone for calculation
holidays (optional): Array of holiday dates
include_weekends (optional): Include weekends in calculation (default: false)

Example:

{
  "start_time": "2025-01-20T08:00:00",
  "end_time": "2025-01-24T18:00:00",
  "business_hours": {
    "start": { "hour": 9, "minute": 0 },
    "end": { "hour": 17, "minute": 30 }
  },
  "holidays": ["2025-01-22"],
  "timezone": "America/New_York"
}

10. `days_until`

Calculate days until a target date or event.

Parameters:

target_date (required): Target date (ISO string, natural language like "next Christmas", or Unix timestamp)
timezone (optional): Timezone for calculation (default: system timezone)
format_result (optional): Return formatted string instead of number (default: false)

Example:

{
  "target_date": "2025-12-25",
  "timezone": "America/New_York"
}

Environment Variables

NODE_ENV: Set to "production" for production use
RATE_LIMIT: Maximum requests per minute (default: 100)
RATE_LIMIT_WINDOW: Rate limit window in milliseconds (default: 60000)
CACHE_SIZE: Maximum cache entries (default: 10000)
DEFAULT_TIMEZONE: Override system timezone detection (e.g., "America/New_York")
MAX_LISTENERS: Maximum concurrent requests (default: 20, minimum: 10)

Performance

All operations complete in < 10ms (after initial load)
Intelligent caching reduces repeated calculations
Sliding window rate limiting prevents abuse
Memory-efficient implementation

Error Handling

The server returns structured errors with codes:

INVALID_TIMEZONE: Invalid timezone specified
INVALID_DATE_FORMAT: Cannot parse the provided date
INVALID_UNIT: Invalid time unit specified
RATE_LIMIT_EXCEEDED: Too many requests
INVALID_RECURRENCE_PATTERN: Invalid recurrence pattern

Development

Current Status

Refactoring completed

Building from source

git clone https://github.com/pshempel/mcp-time-node.git
cd mcp-time-server-node
make setup    # Install dependencies and build
make test     # Run all tests

Running tests

make test         # Run all tests
make coverage     # Run with coverage report
make test-watch   # Run in watch mode for TDD

# If tests fail unexpectedly:
make test-quick   # Fix Jest issues and run tests
make reset        # Full environment reset

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Author

pshempel

Acknowledgments

Built with:

Model Context Protocol SDK
date-fns for date manipulation
date-fns-tz for timezone support

MCP Time Server Node

MCP Time Server Node

Features

Installation

Using npm (recommended)

Using Claude Code (claude mcp add)

Using Claude Desktop

Local Testing

Available Tools

1. get_current_time

2. convert_timezone

3. add_time

4. subtract_time

5. calculate_duration

6. get_business_days

7. next_occurrence

8. format_time

9. calculate_business_hours

10. days_until

Environment Variables

Performance

Error Handling

Development

Current Status

Building from source

Running tests

Contributing

License

Author

Acknowledgments

MCP Time Server Node

Features

Installation

Using npm (recommended)

Using Claude Code (claude mcp add)

Using Claude Desktop

Local Testing

Available Tools

1. get_current_time

2. convert_timezone

3. add_time

4. subtract_time

5. calculate_duration

6. get_business_days

7. next_occurrence

8. format_time

9. calculate_business_hours

10. days_until

Environment Variables

Performance

Error Handling

Development

Current Status

Building from source

Running tests

Contributing

License

Author

Acknowledgments

1. `get_current_time`

2. `convert_timezone`

3. `add_time`

4. `subtract_time`

5. `calculate_duration`

6. `get_business_days`

7. `next_occurrence`

8. `format_time`

9. `calculate_business_hours`

10. `days_until`

1. `get_current_time`

2. `convert_timezone`

3. `add_time`

4. `subtract_time`

5. `calculate_duration`

6. `get_business_days`

7. `next_occurrence`

8. `format_time`

9. `calculate_business_hours`

10. `days_until`