Content
# 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)
```bash
npm install -g mcp-time-server-node
```
### Using Claude Code (claude mcp add)
Add the server to Claude Code:
```bash
# For npm-published version (when available)
claude mcp add mcp-time-server-node
```
```bash
# 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`:
```json
{
"mcpServers": {
"time-server": {
"command": "npx",
"args": ["-y", "mcp-time-server-node"],
"env": {
"NODE_ENV": "production"
}
}
}
}
```
### Local Testing
For testing before npm publish:
```bash
# Build the project
make build
```
```bash
# Test directly
echo '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{}}' | node dist/index.js
```
```bash
# 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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
```bash
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
```bash
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](https://github.com/anthropics/model-context-protocol)
- [date-fns](https://date-fns.org/) for date manipulation
- [date-fns-tz](https://github.com/marnusw/date-fns-tz) for timezone support
