mcp-datetime

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

# 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

Please tell me the current time in date_slash format

Claude

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

npx @modelcontextprotocol/inspector uvx mcp-datetime

Using downloaded source code from GitHub

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.

@ZeparHyfar/mcp-datetime: mcp-datetime

Author

README