dennisonbertram/mcp-date-time

MCP Date-Time Server

A simple, clear MCP (Model Context Protocol) server that provides accurate date and time information to help LLMs avoid generating incorrect dates and times.

Problem Statement

Large Language Models (LLMs) often generate incorrect or outdated dates and times because they:

• Have a fixed knowledge cutoff date
• Don't know the current date/time during inference
• May miscalculate date differences or date arithmetic

This MCP server solves that by providing tools that LLMs can use to get accurate, real-time date and time information.

Features

This server provides 5 simple, well-documented tools:

1. get-current-datetime - Get the current date and time (ALWAYS use this when you need to know "now")
2. parse-date - Parse and validate any date string
3. format-date - Convert dates between different formats
4. calculate-date-difference - Calculate the difference between two dates
5. add-time-to-date - Add or subtract time from a date

Each tool returns structured, consistent JSON that's easy for LLMs to understand and use.

Installation

Quick Start (Pre-built Bundle)

The easiest way to use this server is with the pre-built Node.js bundle:

# 1. Clone and build
git clone <repo-url>
cd mcp-date-time
npm install
npm run build

# 2. Add to Claude Code (using bundled version)
claude mcp add --transport stdio mcp-date-time -- node /path/to/mcp-date-time/dist/index.js

# Or use the standalone bundle (no dependencies needed)
claude mcp add --transport stdio mcp-date-time -- node /path/to/mcp-date-time/dist/index.standalone.js

Using with Claude Desktop

Add to your claude_desktop_config.json:

Option 1: Regular bundle (requires npm install)

{
  "mcpServers": {
    "date-time": {
      "command": "node",
      "args": ["/path/to/mcp-date-time/dist/index.js"]
    }
  }
}

Option 2: Standalone bundle (no dependencies)

{
  "mcpServers": {
    "date-time": {
      "command": "node",
      "args": ["/path/to/mcp-date-time/dist/index.standalone.js"]
    }
  }
}

Development Mode

# Install dependencies
bun install  # or npm install

# Run the server directly with Bun
bun run index.ts

# Or with Node (after building)
npm run build
node dist/index.js

Building from Source

# Install dependencies
npm install

# Build both bundles
npm run build          # Creates dist/index.js (with external deps)
npm run build:standalone  # Creates dist/index.standalone.js (all deps included)

# Test with Node.js
npm run test:node

Tools Documentation

1. get-current-datetime

Purpose: Get the current date and time. Use this whenever you need to know "now".

Input:

{
  "timezone": "America/New_York"  // Optional, defaults to UTC
}

Output:

{
  "iso8601": "2024-11-12T15:30:45.123Z",
  "unix_timestamp": 1699803045,
  "unix_milliseconds": 1699803045123,
  "human_readable": "11/12/2024, 3:30:45 PM",
  "date_only": "11/12/2024",
  "time_only": "3:30:45 PM",
  "timezone": "America/New_York",
  "year": 2024,
  "month": 11,
  "day": 12,
  "hour": 15,
  "minute": 30,
  "second": 45,
  "day_of_week": "Tuesday"
}

Example Usage:

LLM: "What's the current date and time?"
Tool: get-current-datetime with no arguments
Result: Shows current date/time in multiple formats

2. parse-date

Purpose: Parse and validate a date string. Use this to check if a date is valid and get it in standard formats.

Input:

{
  "dateString": "March 15, 2024",
  "timezone": "UTC"  // Optional
}

Output (valid date):

{
  "iso8601": "2024-03-15T00:00:00.000Z",
  "unix_timestamp": 1710460800,
  "unix_milliseconds": 1710460800000,
  "human_readable": "3/15/2024, 12:00:00 AM",
  "date_only": "3/15/2024",
  "time_only": "12:00:00 AM",
  "timezone": "UTC",
  "is_valid": true
}

Output (invalid date):

{
  "is_valid": false,
  "error": "Could not parse date: Invalid date string"
}

Example Usage:

LLM: "Is 'February 30, 2024' a valid date?"
Tool: parse-date with dateString="February 30, 2024"
Result: { "is_valid": false, "error": "..." }

3. format-date

Purpose: Convert a date into a specific format.

Input:

{
  "dateString": "2024-03-15T10:30:00Z",
  "format": "relative",  // "iso", "unix", "date-only", "time-only", "datetime", "relative"
  "timezone": "America/Los_Angeles"  // Optional
}

Output Examples:

• iso: { "formatted": "2024-03-15T10:30:00.000Z", "format": "ISO 8601" }
• unix: { "formatted": "1710499800", "format": "Unix Timestamp" }
• date-only: { "formatted": "2024-03-15", "format": "YYYY-MM-DD" }
• time-only: { "formatted": "10:30:00", "format": "HH:MM:SS" }
• datetime: { "formatted": "3/15/2024, 3:30:00 AM", "format": "Human Readable", "timezone": "America/Los_Angeles" }
• relative: { "formatted": "5 days ago", "format": "Relative", "reference_time": "2024-03-20T10:30:00.000Z" }

Example Usage:

LLM: "Show me that date in relative terms"
Tool: format-date with format="relative"
Result: "5 days ago" (or "3 hours from now", etc.)

4. calculate-date-difference

Purpose: Calculate the time difference between two dates.

Input:

{
  "startDate": "2024-03-15T10:30:00Z",
  "endDate": "2024-03-20T15:45:00Z",
  "unit": "all"  // "days", "hours", "minutes", "seconds", "all"
}

Output (unit="all"):

{
  "milliseconds": 450900000,
  "seconds": 450900,
  "minutes": 7515,
  "hours": 125,
  "days": 5,
  "human_readable": "5 days, 5 hours, 15 minutes, 0 seconds",
  "is_past": false,
  "start_date": "2024-03-15T10:30:00.000Z",
  "end_date": "2024-03-20T15:45:00.000Z"
}

Output (specific unit):

{
  "difference": 5,
  "unit": "days",
  "is_past": false,
  "start_date": "2024-03-15T10:30:00.000Z",
  "end_date": "2024-03-20T15:45:00.000Z"
}

Example Usage:

LLM: "How many days until Christmas 2024?"
Tool 1: get-current-datetime to get today's date
Tool 2: calculate-date-difference with startDate=today, endDate="2024-12-25", unit="days"
Result: Shows number of days

5. add-time-to-date

Purpose: Add or subtract time from a date. Use positive numbers to add, negative to subtract.

Input:

{
  "dateString": "2024-03-15T10:30:00Z",
  "amount": 5,  // Use negative for subtraction
  "unit": "days",  // "years", "months", "days", "hours", "minutes", "seconds"
  "timezone": "UTC"  // Optional
}

Output:

{
  "original_date": "2024-03-15T10:30:00.000Z",
  "result_date": "2024-03-20T10:30:00.000Z",
  "operation": "+5 days",
  "human_readable": "3/20/2024, 10:30:00 AM",
  "timezone": "UTC"
}

Example Usage:

LLM: "What will the date be 3 weeks from today?"
Tool 1: get-current-datetime to get today's date
Tool 2: add-time-to-date with amount=21, unit="days"
Result: Shows date 21 days in the future

Design Principles

This server was designed with LLM usability in mind:

1. Simple, Clear Names - Tool names are descriptive and obvious (e.g., get-current-datetime not gtd)
2. Explicit Descriptions - Each tool has detailed descriptions explaining when and how to use it
3. Structured Output - All responses are consistent JSON with multiple format options
4. Error Handling - Invalid inputs return clear error messages, not exceptions
5. Timezone Support - Optional timezone parameters for global applications
6. No Ambiguity - Tools return multiple formats so LLMs can choose the most appropriate

Common LLM Usage Patterns

Pattern 1: "What's today's date?"

Tool: get-current-datetime
Output: Full date/time info including year, month, day, etc.

Pattern 2: "How many days until [future date]?"

Tool 1: get-current-datetime
Tool 2: calculate-date-difference (startDate=now, endDate=future, unit="days")
Output: Number of days

Pattern 3: "What was the date 2 weeks ago?"

Tool 1: get-current-datetime
Tool 2: add-time-to-date (amount=-14, unit="days")
Output: Date from 2 weeks ago

Pattern 4: "Is this date valid?"

Tool: parse-date
Output: { "is_valid": true/false, ... }

Why This Approach Works

Before this server:

• LLM: "Today is 2023-11-15" (wrong, using training cutoff date)
• User: "No, what's the actual date?"
• LLM: makes a guess (still wrong)

With this server:

• User: "What's today's date?"
• LLM: calls get-current-datetime tool
• Tool: Returns accurate current date
• LLM: "Today is 2024-11-12" (correct!)

Bundle Options

This server provides two bundled versions:

Regular Bundle (dist/index.js - 13KB)

• Use when: You have node_modules available
• Dependencies: Requires @modelcontextprotocol/sdk and zod to be installed
• Size: ~13KB (minimal bundle)
• Install command: npm install required before running

Standalone Bundle (dist/index.standalone.js - 214KB)

• Use when: You want a single file with no external dependencies
• Dependencies: All dependencies bundled inside
• Size: ~214KB (fully self-contained)
• Install command: None! Just copy and run

Which should you use?

• Regular bundle if you're developing or have dependencies installed anyway
• Standalone bundle for distribution, Docker containers, or serverless environments

Both bundles are functionally identical and pass all tests.

Technical Details

• Transport: stdio (works with Claude Code and Claude Desktop)
• Protocol: MCP (Model Context Protocol)
• Runtime: Node.js v18+ or Bun
• Bundler: esbuild (for creating Node.js bundles)
• Dependencies: Minimal (@modelcontextprotocol/sdk + zod)
• Date Library: Native JavaScript Date (no external date libraries needed)

Contributing

Issues and PRs welcome! This server should remain simple and focused on its core mission: providing accurate dates and times to LLMs.

License

MIT

Author

Built to solve the real problem of LLMs generating incorrect dates and times.