An MCP (Model Context Protocol) server that provides powerful datetime manipulation and timer functionality. This server enables standardized datetime operations, flexible formatting, time calculations, and persistent timer tracking across different timezones.

• Time Information

  • Retrieve formatted time information
  • Support for different timezones
  • Optional day information (week number, day of year, etc.)

• Time Calculations

  • Add or subtract time units
  • Support for years, months, days, hours, minutes, seconds
  • Timezone-aware calculations
  • Flexible output formatting

• Timer Functionality

  • Start/stop/delete operations
  • Support for multiple concurrent timers
  • Persistent state across sessions
  • Configurable time formatting (compact/verbose)

# Clone the repository
git clone [repository-url]
cd datetime-mcp

# Install dependencies
npm install

# Build the project
npm run build

You can run this server using Docker in two ways:

# Pull the latest version
docker pull ghcr.io/aaronsb/datetime:latest

# Run the container
docker run -it --rm ghcr.io/aaronsb/datetime

# Build the image
docker build -t datetime-mcp .

# Run the container
docker run -it --rm datetime-mcp

The Docker image:

• Is automatically built and tested via GitHub Actions
• Tagged with both latest and commit-specific versions
• Available on GitHub Container Registry (ghcr.io)

Note: To access the GitHub Container Registry:

1. Go to repository settings
2. Navigate to Actions > General
3. Enable "Read and write permissions" under "Workflow permissions"

Start the server:

npm start

The server provides three main tools through the MCP interface:

// Get current time in New York
{
  "timezone": "America/New_York",
  "format": {
    "style": "full"
  },
  "info": true
}

// Add 2 days to a date
{
  "date": "2025-02-04T00:00:00Z",
  "operation": "add",
  "amount": 2,
  "unit": "days",
  "timezone": "UTC"
}

// Start a new timer
{
  "action": "start",
  "id": "my-timer",
  "description": "Task timer",
  "format": {
    "style": "verbose"
  }
}

# Install dependencies
npm install

# Start in watch mode
npm run dev

The project uses Jest for testing:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

• Built with TypeScript 5.0+
• Uses Node.js runtime
• Implements Model Context Protocol SDK v1.4.1
• Strict TypeScript configuration
• File system persistence for timer state
• Comprehensive test coverage

• Node.js environment
• File system access (for timer persistence)
• System timezone access

• @modelcontextprotocol/sdk: ^1.4.1
• TypeScript and Node.js type definitions
• Development tools: Jest, mock-fs

See LICENSE file for details.