How do I use date-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@date-mcp What's the current time in Tokyo?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

date-mcp

by ploutonconsulting

Overview Schema Related Servers Score Discussions

Python

Local

date-mcp

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.

Related MCP server: MCP Node Time

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:

the value passed to the tool call,
config.ini (see Configuration),
for timezone only, the detected OS timezone,
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):

the path in the DATE_MCP_CONFIG environment variable,
~/.config/date-mcp/config.ini,
./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

Available Tools

3 tools

get_current_timeA

Return the current date and time for an IANA timezone.

Reads the real system clock — this is the tool an agent should call instead of guessing "now". The result carries an explicit UTC offset and broken-out calendar fields so no downstream parsing is ambiguous.

Args: timezone: IANA timezone name (e.g. "UTC", "Europe/London", "America/New_York"). Defaults to "UTC".

Returns: A dict with the ISO-8601 timestamp (with offset), the resolved timezone, the UTC offset, the Unix timestamp, and broken-out calendar fields.

ParametersJSON Schema

Name	Required	Description	Default
`timezone`	No		UTC

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but description discloses it reads the real system clock (not cached) and describes return format. Could add error behavior or rate limits, but sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise, well-structured with Args and Returns sections, no wasted sentences. Front-loaded with purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Low complexity, good annotations? No, but description covers input and output fully. Output schema exists, so return value explanation is appropriate. Complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (timezone) with default. Description explains IANA timezone with examples, far exceeding schema which only has type and default. Schema coverage 0% is compensated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it returns current date and time for an IANA timezone, specifies it reads the real system clock, and distinguishes from guessing 'now'. Purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'this is the tool an agent should call instead of guessing "now"', giving clear when-to-use guidance. No explicit when-not-to-use but siblings are different tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_weekday_dateA

Return the date of a named weekday within the current week.

Answers "what is the date this Wednesday?" deterministically. "This week" is anchored to today in timezone and bounded by week_start.

Args: weekday: Weekday to resolve — full name or 3-letter abbreviation (e.g. "Wednesday", "wed"), case-insensitive. week_start: Day the week starts on. Omit to use the configured default ("Monday" unless overridden in config.ini). timezone: IANA timezone name anchoring "today". Omit to use the configured default (config.ini, else the detected OS zone, else "UTC").

Returns: The target date's calendar fields, the week's start/end dates, and context.

ParametersJSON Schema

Name	Required	Description	Default
`weekday`	Yes
`timezone`	No
`week_start`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses deterministic behavior, anchoring to today via timezone and week_start bounds, and config defaults. However, it does not mention side effects or auth needs (likely none) but still provides good transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured with a summary line, a brief use-case line, and bullet-point Args. It is front-loaded and concise. Could be slightly shorter but no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity, presence of output schema, and thorough parameter explanations, the description provides complete context for usage. It covers return values and defaults adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description's Args section explains each parameter in detail: weekday format (full or 3-letter, case-insensitive), week_start default (Monday), timezone IANA name with fallbacks. This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Return the date of a named weekday within the current week' and gives a concrete example ('what is the date this Wednesday?'). This distinguishes it from sibling tools like 'get_current_time' and 'validate_weekday_date'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the use case (resolving a weekday to a date in the current week) but does not explicitly contrast with siblings or state when not to use. The example helps, but no alternative recommendations are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_weekday_dateA

Validate a weekday+date claim against the current week and correct it.

The weekday name is authoritative: if claimed_date is not that weekday's date in the current week, is_correct is false and corrected_date gives the right date.

Args: weekday: The weekday the caller asserts — name or 3-letter abbreviation. claimed_date: The caller's asserted date, ISO YYYY-MM-DD. week_start: Day the week starts on. Omit to use the configured default. timezone: IANA timezone name anchoring "today". Omit to use the default.

Returns: is_correct, the claimed/corrected dates and weekday names, the week's start/end dates, and context.

ParametersJSON Schema

Name	Required	Description	Default
`weekday`	Yes
`timezone`	No
`week_start`	No
`claimed_date`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully covers behavioral traits: it explains that the weekday name is authoritative, describes the correction logic, and details the return fields including is_correct, corrected_date, and context. This is comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a summary line followed by Args and Returns sections. It is appropriately sized for the complexity, though some redundancy exists (e.g., repeating 'corrected_date' in the summary and Returns).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters and an output schema exists, the description is complete. It explains input semantics, output fields, and behavioral rules, leaving no gaps for an agent to misinterpret.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description thoroughly explains each parameter in the Args section: weekday as name or abbreviation, claimed_date as ISO format, week_start as day week starts, timezone as IANA timezone. This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool validates a weekday+date claim against the current week and corrects it, using specific verbs and resources. It distinguishes itself from siblings by focusing on validation and correction rather than just retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the authoritative nature of the weekday name and the correction logic, providing clear context for when to use this tool. However, it does not explicitly mention when not to use it or compare with sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

3 tool updatesv0.1.0Jul 10, 2026
- First observedget_current_time
- First observedget_weekday_date
- First observedvalidate_weekday_date

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: get_current_time returns current datetime, get_weekday_date resolves a weekday to a date, and validate_weekday_date checks/corrects a claimed date. No overlap in functionality.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern (get_current_time, get_weekday_date, validate_weekday_date) with identical casing and style.

Tool Count5/5

Three tools is well-scoped for a date utility server. Each tool serves a distinct and useful purpose without being too few or too many.

Completeness4/5

The set covers core date operations (current time, weekday resolution, validation) but is missing common utilities like date arithmetic, format conversion, or date difference. Minor gap.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
tick-mcp A
io.github.Cocabadger
A time server that keeps your AI honest about time. Real clock + drift guard, zero dependencies.
Developer Tools
226
Danushkumar-V-mcp-discordOAuth
ai.smithery
An MCP server that integrates with Discord to provide AI-powered features.
Communication Social Media App Automation
2
agentwork-mcp A
io.github.ferm-ai
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Agent Orchestration Autonomous Agents App Automation
2

Related MCP Servers

Temporal Awareness MCP Server
pmbstyle
A
license
Not graded
quality
D
maintenance
A Model Context Protocol (MCP) server that provides AI agents with comprehensive temporal awareness and time calculation capabilities.
Updated a year ago (2025-07-18 01:03 UTC)
3
MIT
MCP Node Time
Developer Tools App Automation
davidan90
A
license
A
quality
D
maintenance
A MCP server that provides timezone-aware date and time operations. This server addresses the common issue where AI assistants provide incorrect date information due to timezone confusion.
Updated a year ago (2025-08-11 09:43 UTC)
4
4
MIT
date
Entertainment & Media
xiaobenyang-com
A
license
A
quality
D
maintenance
An MCP server that provides real-time date, time and time zone information for AI assistants.
Updated 8 months ago (2026-01-09 07:15 UTC)
4
2
Apache 2.0
MCP Learning Project
Developer Tools
vijayanan6
F
license
Not graded
quality
B
maintenance
A custom MCP server providing tools for date/time, calculations, mock weather, and note management, enabling AI agents to perform these tasks via natural language.
Updated 19 days ago (2026-08-18 02:35 UTC)
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ploutonconsulting/date_mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

date-mcp

Design principles

Requirements

Installation

Usage

Configure in an MCP client

Tools

Example

get_weekday_date and validate_weekday_date

Example

Configuration

Development

Contributing

License

Available Tools

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

`get_weekday_date` and `validate_weekday_date`