Date Operations MCP

Date Operations MCP

Lightweight Model Context Protocol (MCP) server exposing common date/time operations powered by date-fns. Built on fastmcp with an HTTP stream transport.

Features

• now: Current timestamp in ISO 8601
• format: Format a date using Unicode tokens (UTS #35)
• add / subtract: Add or subtract a duration from a date
• difference: Compute difference between two dates in a chosen unit
• check: Compare two dates (after, before, equal)

Requirements

• Node.js 18+ (or 20+ recommended)

Install

npm install

Run (dev)

npm run dev
# Server listens on http://localhost:3000 (HTTP stream)

Build & Run (prod)

npm run build
npm start
# Outputs to dist/ and runs Node on dist/index.js

Client integration (MCP over HTTP stream)

This server uses fastmcp with transportType: "httpStream" on port 3000. Point your MCP-capable client at http://localhost:3000.

• Claude Desktop / Cursor: Configure an MCP HTTP server pointing to http://localhost:3000. Refer to your client's MCP HTTP configuration docs and set the URL accordingly.

Note: The server exposes an HTTP stream suitable for MCP-aware clients. It is not a conventional REST API.

Tools

now

• Description: Get the current date/time.
• Parameters: none
• Returns: ISO 8601 string

Example result:

"2025-01-01T12:34:56.789Z"

format

• Description: Format a date.
• Parameters:
  • date (string, ISO 8601)
  • format (string, Unicode tokens per date-fns v4)
• Returns: formatted string

Example call payload (conceptual):

{
  "date": "2025-01-01T00:00:00.000Z",
  "format": "yyyy-MM-dd'T'HH:mm:ssXXX"
}

add

• Description: Add a duration to a date.
• Parameters:
  • date (string, ISO 8601)
  • duration (object) — all numeric fields are required; pass 0 if unused
    • years, months, weeks, days, hours, minutes, seconds
• Returns: ISO 8601 string (result date)

Example:

{
  "date": "2025-01-01T00:00:00.000Z",
  "duration": {
    "years": 0,
    "months": 1,
    "weeks": 0,
    "days": 2,
    "hours": 0,
    "minutes": 30,
    "seconds": 0
  }
}

subtract

• Description: Subtract a duration from a date.
• Parameters: same shape as add
• Returns: ISO 8601 string (result date)

difference

• Description: Difference between two dates in a given unit.
• Parameters:
  • dateFrom (string, ISO 8601)
  • dateTo (string, ISO 8601)
  • unit (enum): seconds | minutes | hours | days | weeks | months | years
• Returns: human-readable string with the numeric difference and unit

Example:

{
  "dateFrom": "2025-01-01T00:00:00.000Z",
  "dateTo": "2025-02-01T00:00:00.000Z",
  "unit": "days"
}

check

• Description: Compare two dates.
• Parameters:
  • firstDate (string, ISO 8601)
  • secondDate (string, ISO 8601)
  • operator (enum): after | before | equal
• Returns: human-readable string indicating the boolean result

Example:

{
  "firstDate": "2025-01-02T00:00:00.000Z",
  "secondDate": "2025-01-01T00:00:00.000Z",
  "operator": "after"
}

Notes and assumptions

• Dates are expected as ISO 8601 strings (UTC recommended).
• format uses Unicode tokens (UTS #35) as in date-fns v4.
• For add/subtract, provide all duration fields; use 0 when not needed.

Project scripts

• dev: tsx index.ts
• build: tsc → emits dist/
• start: node dist/index.js
• test: vitest --coverage

License

MIT © Denny Pradipta