mcp-datetime mcp

v1.0.0 · MCP Tool · registry.pascalai.org

Get current date/time in any timezone, convert between timezones, perform date arithmetic (add/subtract), calculate durations between dates, and format/parse datetime strings.

Operations

OperationDescription
nowCurrent datetime in the specified timezone (default operation).
convertConvert a datetime string to a different timezone.
addAdd or subtract time (days, hours, minutes, months, years) from a datetime.
diffCalculate the duration between two datetimes.
formatFormat a datetime string using a custom or preset format.
parseParse a date string into ISO 8601 format.

Input Parameters

ParameterTypeDescription
operationoptional string Operation to perform. One of now, convert, add, diff, format, parse. Default: "now".
timezoneoptional string IANA timezone name, e.g. "America/Buenos_Aires", "Asia/Tokyo", "Europe/Paris". Default: "UTC".
datetimeoptional string ISO 8601 datetime string. Required for convert, add, diff, format, and parse.
target_timezoneoptional string Target IANA timezone for the convert operation.
deltaoptional object Time delta for the add operation. Fields: days, hours, minutes, months, years (all integers, negative to subtract).
datetime2optional string Second ISO 8601 datetime for the diff operation.
formatoptional string Output format string for the format operation. Supports '%Y-%m-%d', 'ISO8601', 'human', or any strftime-style pattern.

Output Fields

FieldTypeDescription
datetime string Result datetime in ISO 8601 format, including timezone offset.
formatted string Human-readable formatted datetime string, e.g. "Friday, March 13 2026 15:30 ART".
unix_epoch integer Unix timestamp (seconds since 1970-01-01T00:00:00Z).
timezone string IANA timezone name used in the result.
utc_offset string UTC offset string, e.g. "-03:00", "+09:00".
duration object Present for diff. Fields: days (integer), hours (integer), minutes (integer), total_seconds (integer).

Examples

// Current time in Buenos Aires
{
  "operation": "now",
  "timezone": "America/Buenos_Aires"
}
// Output
{
  "datetime": "2026-03-13T15:30:00-03:00",
  "formatted": "Friday, March 13 2026 15:30 ART",
  "unix_epoch": 1773451800,
  "timezone": "America/Buenos_Aires",
  "utc_offset": "-03:00"
}

// Days until year end
{
  "operation": "diff",
  "datetime": "2026-03-13T00:00:00Z",
  "datetime2": "2026-12-31T00:00:00Z"
}
// Output
{
  "duration": {
    "days": 292,
    "hours": 7008,
    "minutes": 420480,
    "total_seconds": 25228800
  }
}

// Add 90 days to a date
{
  "operation": "add",
  "datetime": "2026-03-13T00:00:00Z",
  "delta": { "days": 90 }
}
// Output
{
  "datetime": "2026-06-11T00:00:00Z",
  "formatted": "Thursday, June 11 2026 00:00 UTC",
  "unix_epoch": 1781107200
}

Install & Discovery

Install

ppm install mcp-datetime

Get JSON Schema

GET /v1/packages/mcp-datetime/1.0.0/schema

Discover by keyword

GET /v1/mcp/discover?q=datetime+timezone
Discovery hint: Use this tool whenever an agent needs the current time, must convert between timezones, schedule future events, calculate deadlines, or parse/format date strings from user input or API responses.

PascalAI Usage

uses toolslib;

var DT := LoadTool('mcp-datetime');

// Get current time in Buenos Aires
var Now := DT.Call(JsonObj([
  'operation', 'now',
  'timezone', 'America/Buenos_Aires'
]));
Writeln(Now['formatted']);

// Days remaining until deadline
var Deadline := DT.Call(JsonObj([
  'operation', 'diff',
  'datetime',  '2026-03-13T00:00:00Z',
  'datetime2', '2026-06-30T00:00:00Z'
]));
Writeln('Days remaining: ' + Deadline['duration']['days']);