ZeparHyfar/mcp-datetime

CategoryGeneral
AuthorCommunity
Stars411
PricingFree

Overview

The mcp-datetime server addresses a common LLM limitation: the lack of a reliable, real-time clock and native date manipulation capabilities. Instead of relying on the model's static training data or inconsistent system prompts for the current time, this tool provides a standardized interface for retrieving precise timestamps and formatting dates across different locales. For developers building agents, this is essential for tasks involving scheduling, calculating time deltas, or generating time-stamped logs. It integrates seamlessly via the Model Context Protocol, allowing the AI to call specific time functions as tools rather than guessing the date, which significantly reduces hallucinations in time-sensitive workflows.

Highlights

  • Provides accurate real-time timestamps and date calculations
  • Supports multiple time formats and locale-specific outputs
  • Eliminates LLM hallucinations regarding current dates
  • Easy integration via standard Model Context Protocol

Full Documentation

mcp-datetime

![Python Version](https://www.python.org/downloads/)
![MCP Version](https://github.com/anaisbetts/mcp)
![License](LICENSE)

English | 日本語

A datetime formatting service implemented as an MCP server for the Claude Desktop Application. Supports generation of datetime strings in various formats.

> Note: This package has been tested only on macOS. Windows compatibility has not been verified.

Prerequisites

Before using mcp-datetime, ensure you have the following tools installed:

  • Python 3.12 or later
  • uv (Python package installer)
  • uvx (Python package runner)

Features

  • ✨ Support for various datetime formats
  • 🇯🇵 Japanese language support
  • 📁 Optimized formats for filename generation
  • 🌏 Accurate timezone handling
  • 🔧 Seamless integration with Claude Desktop App

MCP Server Components

Tools

The server implements one tool:

  • get_datetime: Get current date and time in various formats
- Takes "format" as a required string argument - Returns formatted datetime string based on specified format - Supports multiple format types including standard, Japanese, and ISO formats

Usage with Claude Desktop App

Add the following to your config file:

Config file location (macOS):
~/Library/Application Support/Claude/claude_desktop_config.json

json
{
  "mcpServers": {
    "mcp-datetime": {
      "command": "uvx",
      "args": ["mcp-datetime"]
    }
  }
}

About Installation

If you need to install the package directly (e.g., for development or source code inspection), you can use one of these methods:

  • Install from PyPI
bash
pip install mcp-datetime
  • Install from GitHub Source
bash
git clone https://github.com/ZeparHyfar/mcp-datetime.git
  cd mcp-datetime
  pip install -e .
  • Example claude_desktop_config.json for manual installation
json
{
    "mcpServers": {
      "mcp-datetime": {
        "command": "python",
        "args": ["-m", "mcp_datetime"],
        "env": {
          "PYTHON": "/path/to/your/python"
        }
      }
    }
  }

Replace "/path/to/your/python" with your actual Python interpreter path
> e.g., "/usr/local/bin/python3" or "/Users/username/.pyenv/versions/3.12.0/bin/python3"

Basic Examples

  • Command format
code
# Standard datetime format
  call datetime-service.get_datetime {"format": "datetime"}
  # Result: 2024-12-10 00:54:01

# Japanese format
  call datetime-service.get_datetime {"format": "datetime_jp"}
  # Result: 2024年12月10日 00時54分01秒


# Filename format
  call datetime-service.get_datetime {"format": "filename_md"}
  # Result: 20241210005401.md

  • Claude Desktop App prompt examples

- User

code
Please tell me the current time in date_slash format

- Claude

code
I'll get the current date in date_slash format.

The current date is 2024/12/12

Supported Formats

| Format Name | Example | Description |
| ------------ | --------------------------- | ---------------------------- |
| date | 2024-12-10 | Standard date format |
| date_slash | 2024/12/10 | Date with slashes |
| date_jp | 2024年12月10日 | Japanese date format |
| datetime | 2024-12-10 00:54:01 | Standard datetime |
| datetime_jp | 2024年12月10日 00時54分01秒 | Japanese datetime |
| datetime_t | 2024-12-10T00:54:01 | DateTime with T separator |
| compact | 20241210005401 | Compact format for IDs |
| compact_date | 20241210 | Compact date only |
| compact_time | 005401 | Compact time only |
| filename_md | 20241210005401.md | Markdown filename |
| filename_txt | 20241210005401.txt | Text filename |
| filename_log | 20241210005401.log | Log filename |
| iso | 2024-12-10T00:54:01+0900 | ISO 8601 format |
| iso_basic | 20241210T005401+0900 | Basic ISO format |
| log | 2024-12-10 00:54:01.123456 | Log format with microseconds |
| log_compact | 20241210_005401 | Compact log format |
| time | 00:54:01 | Time only |
| time_jp | 00時54分01秒 | Japanese time format |

Debugging

Since MCP servers run over stdio, debugging can be challenging. We recommend using the MCP Inspector:

  • Using PyPI package
code
npx @modelcontextprotocol/inspector uvx mcp-datetime
  • Using downloaded source code from GitHub
code
git clone https://github.com/ZeparHyfar/mcp-datetime.git
  npx @modelcontextprotocol/inspector uvx --directory ./mcp-datetime run mcp-datetime

License

This project is licensed under the MIT License - see the LICENSE file for details.

View official source
Join our Telegram