Date

CI License: MIT Python 3.10+

An MCP server that gives AI agents accurate date, time, timezone, and interval information.

Large language models are notoriously unreliable at knowing what "now" is, computing durations, and reasoning across timezones — they guess, and they guess wrong. date-mcp closes that gap by exposing deterministic, system-clock-backed tools an agent can call for the truth instead of hallucinating it.

Design principles

• Correctness first. Every value is derived from the real system clock and the IANA timezone database — never from a model's sense of time.
• No ambiguity. All timestamps are ISO-8601 / RFC-3339 with an explicit UTC offset. Nothing naive ever leaves the server.
• Self-describing results. Tools return the ISO string and broken-out calendar fields, so consumers don't have to re-parse.

Requirements

• Python 3.10+

Installation

pip install date-mcp

Or, from source:

git clone https://github.com/ploutonconsulting/date-mcp.git
cd date-mcp
pip install -e ".[dev]"

Usage

Run the server over stdio:

date-mcp
# or
python -m date_mcp

Configure in an MCP client

For a client that reads a JSON config (e.g. Claude Desktop), add:

{
  "mcpServers": {
    "date-mcp": {
      "command": "date-mcp"
    }
  }
}

Tools

Tool	Description
get_current_time(timezone="UTC")	Current date/time for an IANA timezone, as ISO-8601 with offset plus broken-out calendar fields.
get_weekday_date(weekday, week_start=None, timezone=None)	The date of a named weekday within the current week.
validate_weekday_date(weekday, claimed_date, week_start=None, timezone=None)	Validate a weekday+date claim against the current week and correct it if wrong.

The tool surface is expanding as requirements are agreed (timezone conversion, duration/interval maths, business-day calculations, parsing). See CHANGELOG.md and open a feature request.

Example

get_current_time(timezone="Europe/London")
# {
#   "iso8601": "2026-07-10T14:32:05.123456+01:00",
#   "timezone": "Europe/London",
#   "utc_offset": "+0100",
#   "unix": 1783434725.123456,
#   "year": 2026, "month": 7, "day": 10,
#   "hour": 14, "minute": 32, "second": 5, "microsecond": 123456,
#   "weekday": "Friday", "iso_weekday": 5, "day_of_year": 191
# }

get_weekday_date and validate_weekday_date

These answer "what date is this Wednesday?" and "is Friday actually the 11th?" deterministically — "this week" is anchored to today in timezone and bounded by week_start, never guessed by the model.

Both tools take:

• weekday — full name or 3-letter abbreviation (e.g. "Wednesday", "wed"), case-insensitive.
• week_start — day the week starts on (name or abbreviation). Optional.
• timezone — IANA timezone name anchoring "today". Optional.

validate_weekday_date additionally takes claimed_date — the caller's asserted date, ISO YYYY-MM-DD.

Every optional parameter resolves through the same precedence chain:

1. the value passed to the tool call,
2. config.ini (see Configuration),
3. for timezone only, the detected OS timezone,
4. the built-in default — "UTC" for timezone, "Monday" for week_start.

weekday_format ("full" or "abbreviated") is not a tool parameter — it is config-only and applies to the weekday names in every response.

get_weekday_date returns the target date's calendar fields (iso_date, iso_weekday, year, month, day, day_of_year), the formatted weekday name, the week's week_start/week_start_date/week_end_date, and the echoed timezone and reference_date.

validate_weekday_date returns is_correct, the weekday name, the claimed_date/claimed_weekday (the actual weekday of claimed_date, useful as a diagnostic when the claim is wrong), the corrected_date/corrected_weekday, the week's week_start/week_start_date/week_end_date, and the echoed timezone and reference_date.

Example

If today is Friday 10 July 2026 and an agent claims "Friday 11 July 2026":

validate_weekday_date(weekday="Friday", claimed_date="2026-07-11")
# {
#   "is_correct": false,
#   "weekday": "Friday",
#   "claimed_date": "2026-07-11",
#   "claimed_weekday": "Saturday",
#   "corrected_date": "2026-07-10",
#   "corrected_weekday": "Friday",
#   "week_start": "Monday",
#   "week_start_date": "2026-07-06",
#   "week_end_date": "2026-07-12",
#   "timezone": "UTC",
#   "reference_date": "2026-07-10"
# }

claimed_date (11th) is a Saturday, not a Friday, so the claim is corrected to the 10th — the actual Friday in the current week.

Configuration

date-mcp reads an optional config.ini to set defaults for timezone, week_start, and weekday_format. Every setting is optional; anything omitted falls back to a built-in default.

Discovery order (first existing file wins):

1. the path in the DATE_MCP_CONFIG environment variable,
2. ~/.config/date-mcp/config.ini,
3. ./config.ini (the server's working directory).

Settings:

Section	Key	Description	Default
[defaults]	timezone	IANA timezone used when a tool call omits timezone.	detected OS zone, else UTC
[defaults]	week_start	Day the week starts on (full name or 3-letter abbreviation).	Monday
[output]	weekday_format	Weekday-name rendering: full (Wednesday) or abbreviated (Wed).	full

When timezone is omitted from both the tool call and config.ini, date-mcp detects the machine's local IANA zone via tzlocal and falls back to UTC only if that detection fails.

A malformed config file or an invalid setting (unknown timezone, unrecognised week_start, or bad weekday_format) raises when the server starts (fail-fast) rather than silently falling back.

See config.example.ini for a commented sample.

Development

pip install -e ".[dev]"
pre-commit install
ruff check . && ruff format --check .
mypy
pytest

Contributing

Contributions are welcome — see CONTRIBUTING.md and our Code of Conduct. To report a vulnerability, see SECURITY.md.

License

MIT © Pierre Oosthuizen