BrainyCalc Docs — Date & Time

API Reference

MCP Time Server

Deterministic tools for date differences, workday computations, Unix timestamp conversions, age calculations, worldwide timezone lookups, duration arithmetic, and full MCP Time Server integration for AI agents.

Date Calculators

datetime_difference

Calculate total duration and difference between two dates in days, hours, minutes, and formatted weeks/days.

date arithmetic

Parameter	Type	Required	Description
`startDate`	string	required	Start date in ISO 8601 format (`YYYY-MM-DD`)
`endDate`	string	required	End date in ISO 8601 format (`YYYY-MM-DD`)

Request / Response

// Request
{ "startDate": "2026-01-01", "endDate": "2026-08-08" }

// Response
{
  "startDate": "2026-01-01",
  "endDate": "2026-08-08",
  "difference": {
    "totalDays": 219,
    "totalHours": 5256,
    "totalMinutes": 315360,
    "formatted": "31 weeks and 2 days"
  }
}

datetime_add_subtract

Add or subtract specified amounts of days, weeks, months, years, hours, or minutes to/from a date.

date arithmetic

Parameter	Type	Required	Description
`startDate`	string	required	Base start date (`YYYY-MM-DD`)
`amount`	number	required	Quantity of units to shift
`unit`	enum	required	`days` · `weeks` · `months` · `years` · `hours` · `minutes`
`operation`	enum	optional	`add` (default) or `subtract`

Request / Response

// Add 14 days to August 8, 2026
{ "startDate": "2026-08-08", "amount": 14, "unit": "days", "operation": "add" }

{
  "initialDate": "2026-08-08",
  "operation": "add",
  "amount": 14,
  "unit": "days",
  "resultDate": "2026-08-22T00:00:00.000Z"
}

datetime_work_days

Calculate working days between two dates, with an option to include or exclude weekends.

business

Parameter	Type	Required	Description
`startDate`	string	required	Start date (`YYYY-MM-DD`)
`endDate`	string	required	End date (`YYYY-MM-DD`)
`includeWeekends`	boolean	optional	Include weekends in total count (default: `false`)

Note

Public holidays are not automatically excluded. Use datetime_add_subtract to offset for specific holidays.

Request / Response

{ "startDate": "2026-08-03", "endDate": "2026-08-14", "includeWeekends": false }

{
  "startDate": "2026-08-03",
  "endDate": "2026-08-14",
  "workDaysCount": 10,
  "weekendsIncluded": false
}

datetime_calculate_age

Calculate exact age in years, months, and days relative to a target date or today.

age

Parameter	Type	Required	Description
`birthDate`	string	required	Birth date (`YYYY-MM-DD`)
`targetDate`	string	optional	Reference date (defaults to current system date)

Request / Response

{ "birthDate": "1990-05-15", "targetDate": "2026-08-08" }

{
  "birthDate": "1990-05-15",
  "years": 36,
  "months": 2,
  "days": 24,
  "totalDays": 13234,
  "formatted": "36 years, 2 months, 24 days"
}

datetime_unix_timestamp

Convert date strings to Unix timestamps (seconds & milliseconds) or convert numeric timestamps back to ISO dates.

conversion

Parameter	Type	Required	Description
`value`	string	required	ISO date string or numeric timestamp string
`mode`	enum	optional	`to_timestamp` (default) or `from_timestamp`

Request / Response

{ "value": "2026-08-08T12:00:00Z", "mode": "to_timestamp" }

{
  "dateString": "2026-08-08T12:00:00Z",
  "timestampSeconds": 1786262400,
  "timestampMs": 1786262400000
}

datetime_day_of_week

Determine day name, weekend status, and day number of the year for any date.

calendar

Parameter	Type	Required	Description
`date`	string	required	Date string (`YYYY-MM-DD`)

Request / Response

{ "date": "2026-08-08" }

{
  "date": "2026-08-08",
  "dayName": "Saturday",
  "isWeekend": true,
  "dayOfYear": 220
}

Extended Date Tools

calc_age

Extended age calculator returning years, months, days, total days, and total weeks from a birth date.

extended date

Parameter	Type	Required	Description
`birth_date`	string	required	Birth date (`YYYY-MM-DD`)
`reference_date`	string	optional	Reference date (defaults to today)

Request / Response

{ "birth_date": "1995-10-20", "reference_date": "2026-08-08" }

{
  "birth_date": "1995-10-20",
  "years": 30,
  "months": 9,
  "days": 19,
  "total_days": 11250,
  "total_weeks": 1607
}

calc_date_diff

Calculate date difference across multiple metrics: exact days, weeks, months, and years.

extended date

Parameter	Type	Required	Description
`date1`	string	required	First date (`YYYY-MM-DD`)
`date2`	string	required	Second date (`YYYY-MM-DD`)

Request / Response

{ "date1": "2026-01-01", "date2": "2026-08-08" }

{
  "date1": "2026-01-01",
  "date2": "2026-08-08",
  "days": 219,
  "weeks": 31.29,
  "months": 7.19,
  "years": 0.5997
}

calc_day_counter

Count the exact number of days and relative periods between a start date and an end date.

extended date

Parameter	Type	Required	Description
`start_date`	string	required	Start date (`YYYY-MM-DD`)
`end_date`	string	required	End date (`YYYY-MM-DD`)

Request / Response

{ "start_date": "2026-01-01", "end_date": "2026-12-31" }

{
  "date1": "2026-01-01",
  "date2": "2026-12-31",
  "days": 364,
  "weeks": 52,
  "months": 11.96,
  "years": 0.9973
}

calc_day_of_week

Get weekday name, month name, day of month, year, and calculated week number for a given date.

calendar

Parameter	Type	Required	Description
`date`	string	required	Target date (`YYYY-MM-DD`)

Request / Response

{ "date": "2026-08-08" }

{
  "date": "2026-08-08",
  "day_of_week": "Saturday",
  "month": "August",
  "day_number": 8,
  "year": 2026,
  "week_number": 32
}

Time & World Clock

calc_local_time

Retrieves current local time, formatted date, runtime IANA timezone, Unix timestamp, and timezone offset.

world time

Parameter	Type	Required	Description
No parameters required

Request / Response

// Request
{}

// Response
{
  "local_time": "11:43:00",
  "local_date": "Saturday, August 8, 2026",
  "timezone": "America/New_York",
  "timezone_display": "America/New York",
  "timestamp": 1786262580000,
  "timezone_offset_mins": 240
}

calc_world_time

Search current time across global cities/countries, filter by region, or perform direct IANA timezone queries.

world time

Parameter	Type	Required	Description
`query`	string	optional	Country or city name (e.g. `"Tokyo"`, `"United Kingdom"`)
`region`	enum	optional	`All` · `Africa` · `Americas` · `Asia` · `Europe` · `Oceania`
`timezone`	string	optional	Direct IANA timezone (e.g. `"Asia/Kabul"`)
`offset_hours`	number	optional	UTC offset hours fallback
`offset_minutes`	number	optional	UTC offset minutes fallback

Request / Response

{ "query": "Tokyo" }

{
  "query": "Tokyo",
  "region": "All",
  "match_count": 1,
  "results": [
    {
      "flag": "🇯🇵",
      "country": "Japan",
      "city": "Tokyo",
      "timezone": "Asia/Tokyo",
      "region": "Asia",
      "time": "00:43:00",
      "date": "Sun, Aug 9",
      "offset_string": "GMT+9"
    }
  ]
}

calc_time_duration

Calculates time duration between two times of day (HH:MM or HH:MM:SS), handling overnight roll-overs automatically.

time math

Parameter	Type	Required	Description
`start`	string	required	Start time (`HH:MM` or `HH:MM:SS`)
`end`	string	required	End time (`HH:MM` or `HH:MM:SS`)

Request / Response

{ "start": "09:00:00", "end": "17:30:00" }

{
  "start": "09:00:00",
  "end": "17:30:00",
  "hours": 8,
  "minutes": 30,
  "seconds": 0,
  "total_seconds": 30600,
  "display": "8h 30m 0s"
}

calc_time_add

Add or subtract hours, minutes, and seconds to/from a base time string.

time math

Parameter	Type	Required	Description
`time`	string	required	Base time string (`HH:MM` or `HH:MM:SS`)
`add_hours`	number	optional	Hours to add (use negative to subtract)
`add_minutes`	number	optional	Minutes to add (use negative to subtract)
`add_seconds`	number	optional	Seconds to add (use negative to subtract)

Request / Response

{ "time": "14:15:00", "add_hours": 3, "add_minutes": 45 }

{
  "original": "14:15:00",
  "result": "18:00:00",
  "added": { "hours": 3, "minutes": 45, "seconds": 0 }
}

calc_hours_between

Calculate elapsed hours, minutes, and seconds between two times. Alias for calc_time_duration.

time math

Parameter	Type	Required	Description
`start`	string	required	Start time (`HH:MM` or `HH:MM:SS`)
`end`	string	required	End time (`HH:MM` or `HH:MM:SS`)

Request / Response

{ "start": "08:30:00", "end": "16:45:00" }

{
  "start": "08:30:00",
  "end": "16:45:00",
  "hours": 8,
  "minutes": 15,
  "seconds": 0,
  "total_seconds": 29700,
  "display": "8h 15m 0s"
}

MCP Time Server Tools

MCP Time Server · @brainycalc/mcptimeserver v1.0.1

The tools below are part of the MCP Time Server — a Model Context Protocol server that exposes all datetime functionality to AI agents. Install with npx -y @brainycalc/mcptimeserver and add to your MCP client config. All 27 tools run over stdio with no HTTP port needed. See the npm package for full setup instructions.

now

Get the current date and time in any IANA timezone and custom format.

mcp toolcurrent time

Parameter	Type	Required	Description
`format`	string	optional	Format string (e.g. `YYYY-MM-DD HH:mm:ss`). Defaults to ISO 8601.
`timezone`	string	optional	IANA timezone (e.g. `America/New_York`). Defaults to UTC.

MCP Tool Call / Response

// Tool call arguments
{
  "format": "YYYY-MM-DD HH:mm:ss",
  "timezone": "Europe/London"
}

// Result
"2026-08-08 16:43:00"

format_date

Format a date/time value using custom format tokens, with optional input format parsing.

mcp toolformatting

Parameter	Type	Required	Description
`date`	string	required	Date string to format
`format`	string	required	Output format string (e.g. `dddd, MMMM D, YYYY`)
`inputFormat`	string	optional	Input format hint when the date uses a non-standard layout

MCP Tool Call / Response

{ "date": "2026-08-08", "format": "dddd, MMMM D, YYYY" }

"Saturday, August 8, 2026"

// With inputFormat
{ "date": "08/08/2026", "format": "YYYY-MM-DD", "inputFormat": "DD/MM/YYYY" }
"2026-08-08"

parse_date

Parse a date string and return a structured object with all calendar components.

mcp toolparsing

Parameter	Type	Required	Description
`date`	string	required	ISO date string to parse (e.g. `2026-08-08T15:30:00`)

MCP Tool Call / Response

{ "date": "2026-08-08T15:30:00" }

{
  "year": 2026, "month": 8, "day": 8,
  "weekday": "Saturday", "week": 32, "isoWeek": 32,
  "quarter": 3, "dayOfYear": 220,
  "unix": 1786264200,
  "hour": 15, "minute": 30, "second": 0
}

adjust_time

Add or subtract any time unit from a date — from milliseconds to years.

mcp toolarithmetic

Parameter	Type	Required	Description
`date`	string	required	Base date (`YYYY-MM-DD`)
`amount`	number	required	Quantity to shift
`unit`	enum	required	`millisecond` · `second` · `minute` · `hour` · `day` · `week` · `month` · `quarter` · `year`
`operation`	enum	optional	`add` (default) or `subtract`

MCP Tool Call / Response

{ "date": "2026-08-08", "amount": 2, "unit": "months", "operation": "subtract" }

{ "result": "2026-06-08" }

date_diff

Calculate the difference between two dates in any unit, with optional fractional output.

mcp toolarithmetic

Parameter	Type	Required	Description
`date1`	string	required	First date (`YYYY-MM-DD`)
`date2`	string	required	Second date (`YYYY-MM-DD`)
`unit`	enum	required	`millisecond` · `second` · `minute` · `hour` · `day` · `week` · `month` · `quarter` · `year`
`float`	boolean	optional	Return fractional result (default: `false`)

MCP Tool Call / Response

{ "date1": "2026-01-01", "date2": "2026-08-08", "unit": "days" }

{ "difference": 219, "unit": "days" }

boundary_of

Get the start or end boundary of a time unit for a given date (e.g. start of month, end of year).

mcp toolcalendar

Parameter	Type	Required	Description
`date`	string	required	Reference date (`YYYY-MM-DD`)
`unit`	enum	required	`year` · `quarter` · `month` · `week` · `isoWeek` · `day` · `hour` · `minute` · `second`
`edge`	enum	required	`start` or `end`

MCP Tool Call / Response

{ "date": "2026-08-08", "unit": "month", "edge": "start" }
{ "result": "2026-08-01T00:00:00.000Z" }

{ "date": "2026-08-08", "unit": "month", "edge": "end" }
{ "result": "2026-08-31T23:59:59.999Z" }

convert_timezone

Convert a date/time from one IANA timezone to another. Uses JavaScript's built-in Intl.DateTimeFormat.

mcp tooltimezone

Parameter	Type	Required	Description
`date`	string	required	Date/time string to convert
`fromTimezone`	string	required	Source IANA timezone (e.g. `Europe/London`)
`toTimezone`	string	required	Target IANA timezone (e.g. `Asia/Tokyo`)

MCP Tool Call / Response

{
  "date": "2026-08-08T12:00:00",
  "fromTimezone": "Europe/London",
  "toTimezone": "Asia/Tokyo"
}

{
  "original": "2026-08-08T12:00:00",
  "converted": "2026-08-08T21:00:00",
  "fromTimezone": "Europe/London",
  "toTimezone": "Asia/Tokyo"
}

work_days

Calculate working days between two dates. Weekends excluded by default; set includeWeekends to override.

mcp toolbusiness

Parameter	Type	Required	Description
`startDate`	string	required	Start date (`YYYY-MM-DD`)
`endDate`	string	required	End date (`YYYY-MM-DD`)
`includeWeekends`	boolean	optional	Count weekends too (default: `false`)

MCP Tool Call / Response

{ "startDate": "2026-08-03", "endDate": "2026-08-14" }

{ "workDays": 10, "includeWeekends": false }

world_time

Look up current time for a city, country, geographic region, direct IANA timezone, or UTC offset.

mcp toolworld time

Parameter	Type	Required	Description
`query`	string	optional	City or country name (e.g. `"Tokyo"`)
`region`	enum	optional	`All` · `Africa` · `Americas` · `Asia` · `Europe` · `Oceania`
`timezone`	string	optional	Direct IANA timezone string
`offset_hours`	number	optional	UTC offset hours fallback
`offset_minutes`	number	optional	UTC offset minutes fallback

MCP Tool Call / Response

{ "timezone": "Asia/Tokyo" }

{
  "flag": "🇯🇵", "country": "Japan", "city": "Tokyo",
  "timezone": "Asia/Tokyo", "time": "01:43:00",
  "date": "Sun, Aug 9", "offset_string": "GMT+9"
}

duration

Create or inspect a duration from an ISO 8601 string, milliseconds, or a structured object.

mcp toolduration

Parameter	Type	Required	Description
`input`	string \| number \| object	required	ISO 8601 string (`P1Y2M3DT4H`), milliseconds, or object (`{"hours": 2, "minutes": 30}`)
`unit`	string	optional	Unit when `input` is a number (e.g. `milliseconds`)
`output`	enum	optional	`humanize` · `iso` · `milliseconds` · `object`

MCP Tool Call / Response

{ "input": { "hours": 2, "minutes": 30 }, "output": "humanize" }

"2 hours"

{ "input": "P1Y2M3DT4H", "output": "object" }

{ "years": 1, "months": 2, "days": 3, "hours": 4 }

unix_convert

Convert between human-readable dates and Unix timestamps (in seconds). Bidirectional.

mcp toolconversion

Parameter	Type	Required	Description
`date`	string	optional	ISO date string (for `to_unix` mode)
`fromUnix`	number	optional	Unix timestamp in seconds (for `from_unix` mode)
`mode`	enum	required	`to_unix` or `from_unix`

MCP Tool Call / Response

// Date → Unix
{ "date": "2026-08-08T12:00:00Z", "mode": "to_unix" }
{ "unix": 1786262400 }

// Unix → Date
{ "fromUnix": 1786262400, "mode": "from_unix" }
{ "date": "2026-08-08T12:00:00.000Z" }

calc_age

Calculate age in years from a birth date to today or an optional reference date.

mcp toolage

Parameter	Type	Required	Description
`birthDate`	string	required	Birth date (`YYYY-MM-DD`)
`targetDate`	string	optional	Reference date (defaults to today)

MCP Tool Call / Response

{ "birthDate": "2000-01-15", "targetDate": "2026-08-08" }

{ "age": 26, "birthDate": "2000-01-15" }

Format Token Reference

All format tokens used by format_date, now, utc_date, and other tools that accept a format parameter.

Token	Meaning	Example
`YYYY`	Four-digit year	2026
`YY`	Two-digit year	26
`M`	Month number (1–12)	8
`MM`	Month, zero-padded	08
`MMM`	Abbreviated month name	Aug
`MMMM`	Full month name	August
`D`	Day of month (1–31)	8
`DD`	Day, zero-padded	08
`d`	Numeric weekday (0–6)	6
`dd`	Minimal weekday name	Sa
`ddd`	Abbreviated weekday name	Sat
`dddd`	Full weekday name	Saturday
`H`	Hour, 24-hour (0–23)	15
`HH`	Hour, zero-padded 24h	15
`h`	Hour, 12-hour (1–12)	3
`hh`	Hour, zero-padded 12h	03
`a`	am/pm	pm
`A`	AM/PM	PM
`m`	Minute (0–59)	5
`mm`	Minute, zero-padded	05
`s`	Second (0–59)	9
`ss`	Second, zero-padded	09
`SSS`	Milliseconds	042
`Z`	UTC offset	+01:00

Example: YYYY-MM-DD HH:mm:ss → 2026-08-08 15:05:09