date-mcp

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