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

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables date and time operations including formatting, arithmetic, comparisons, and duration calculations using date-fns library. Provides tools for getting current time, adding/subtracting durations, finding differences between dates, and comparing dates.

Date Operations MCP