MCP Time Server
A Model Context Protocol (MCP) server for time tracking and timezone conversion utilities. This server provides AI assistants with the ability to get current time in any timezone and convert times between different timezones.
Features
- Current Time: Get the current time in any IANA timezone
- Time Conversion: Convert time from one timezone to another
- Daylight Saving Time Support: Automatically detects and handles DST
- Express HTTP Server: REST API with health checks
- Docker Support: Ready for containerized deployment
- TypeScript: Full TypeScript support with type safety
Prerequisites
- Node.js 20 or later
- npm or yarn
- Docker (optional, for containerized deployment)
Installation
Local Development
- Clone the repository:```bash
git clone <repository-url>
cd mcp-time
2. Install dependencies:```bash
npm install
- Create environment file (optional):```bash
cp .env.example .env
Edit .env with your configuration
### Environment Variables
- `PORT`: Server port (default: 3000)
- `NODE_ENV`: Environment mode (development/production)
- `TZ`: Timezone for the server (default: Asia/Hong_Kong)
## Usage
### Development
Start the development server with hot reload:```bash
npm run dev
Production
Build and start the production server:```bash
npm run build
npm start
### Available Scripts
- `npm run build` - Build TypeScript to JavaScript
- `npm run dev` - Start development server with hot reload
- `npm start` - Start production server
- `npm run lint` - Run ESLint
- `npm run lint:fix` - Fix ESLint issues automatically
- `npm test` - Run tests
## MCP Tools
The server provides two MCP tools:
### 1. get_current_time
Get the current time in a specified timezone.
**Parameters:**
- `timezone` (string): IANA timezone name (e.g., 'America/New_York', 'Europe/London')
**Example Response:**```json
{
"timezone": "America/New_York",
"datetime": "2024-01-15T10:30:00-05:00",
"is_dst": false
}
2. convert_time
Convert time from one timezone to another.
Parameters:
- source_timezone (string): Source IANA timezone name
- time (string): Time in 24-hour format (HH:MM)
- target_timezone (string): Target IANA timezone name
Example Response:```json
{
"source": {
"timezone": "America/New_York",
"datetime": "2024-01-15T10:30:00-05:00",
"is_dst": false
},
"target": {
"timezone": "Asia/Tokyo",
"datetime": "2024-01-16T00:30:00+09:00",
"is_dst": false
},
"time_difference": "+14h"
}
## API Endpoints
### Health Check```
GET /health
Returns server status and basic information.
MCP Endpoint```
POST /mcp
GET /mcp (for SSE notifications)
DELETE /mcp (for session termination)
Main MCP communication endpoint. Requires `mcp-session-id` header for stateful connections.
## Docker Deployment
### Build Docker Image```bash
docker build -t mcp/time .
Run Container```bash
docker run -p 3002:3002 -e PORT=3002 mcp/time
### Docker Compose```yaml
version: '3.8'
services:
mcp-time-server:
build: .
ports:
- "3002:3002"
environment:
- PORT=3002
- NODE_ENV=production
- TZ=Asia/Hong_Kong
restart: unless-stopped
Supported Timezones
This server supports all IANA timezone names. Common examples include:
Americas:
- America/New_York (Eastern Time)
- America/Chicago (Central Time)
- America/Denver (Mountain Time)
- America/Los_Angeles (Pacific Time)
- America/Sao_Paulo (Brazil)
Europe:
- Europe/London (GMT/BST)
- Europe/Paris (CET/CEST)
- Europe/Berlin (CET/CEST)
- Europe/Moscow (MSK)
Asia:
- Asia/Tokyo (JST)
- Asia/Shanghai (CST)
- Asia/Hong_Kong (HKT)
- Asia/Singapore (SGT)
- Asia/Kolkata (IST)
Others:
- UTC (Coordinated Universal Time)
- Australia/Sydney (AEDT/AEST)
Error Handling
The server includes comprehensive error handling for:
- Invalid timezone names
- Invalid time formats
- Network connectivity issues
- Session management errors
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/new-feature - Make your changes and add tests
- Run linting:
npm run lint:fix - Commit your changes:
git commit -am 'Add new feature' - Push to the branch:
git push origin feature/new-feature - Submit a pull request
License
MIT License - see the LICENSE file for details.
Support
For issues and questions:
1. Check the Issues section
2. Create a new issue with detailed information
3. Include error logs and system information
Architecture
The server is built with:
- Express.js: HTTP server framework
- MCP SDK: Model Context Protocol implementation
- date-fns: Date manipulation and formatting
- Zod: Schema validation
- TypeScript: Type safety and development experience
The server maintains stateful connections using session IDs and provides both synchronous tool calls and asynchronous notifications through Server-Sent Events (SSE).
