mcp-time

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

1. Clone the repository:

git clone <repository-url>
cd mcp-time

2. Install dependencies:

npm install

3. Create environment file (optional):

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:

npm run dev

Production

Build and start the production server:

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:

{
  "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:

{
  "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

docker build -t mcp/time .

Run Container

docker run -p 3002:3002 -e PORT=3002 mcp/time

Docker Compose

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

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes and add tests
4. Run linting: npm run lint:fix
5. Commit your changes: git commit -am 'Add new feature'
6. Push to the branch: git push origin feature/new-feature
7. Submit a pull request

License

MIT License - see the file for details.

Support

For issues and questions:

1. Check the 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).