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

{
  "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

  pip install mcp-datetime
  

• Install from GitHub Source

  git clone https://github.com/ZeparHyfar/mcp-datetime.git
  cd mcp-datetime
  pip install -e .
  

• Example claude_desktop_config.json for manual installation

  {
    "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.