MCP Datetime

1# mcp-datetime
2 
3[![Python Version](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
4[![MCP Version](https://img.shields.io/badge/mcp-1.1.1-green.svg)](https://github.com/anaisbetts/mcp)
5[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6 
7English | [日本語](README_ja.md)
8 
9A datetime formatting service implemented as an MCP server for the Claude Desktop Application. Supports generation of datetime strings in various formats.
10 
11> **Note**: This package has been tested only on macOS. Windows compatibility has not been verified.
12 
13## Prerequisites
14 
15Before using mcp-datetime, ensure you have the following tools installed:
16 
17- Python 3.12 or later
18- uv (Python package installer)
19- uvx (Python package runner)
20 
21## Features
22 
23- ✨ Support for various datetime formats
24- 🇯🇵 Japanese language support
25- 📁 Optimized formats for filename generation
26- 🌏 Accurate timezone handling
27- 🔧 Seamless integration with Claude Desktop App
28 
29## MCP Server Components
30 
31### Tools
32 
33The server implements one tool:
34 
35- `get_datetime`: Get current date and time in various formats
36  - Takes "format" as a required string argument
37  - Returns formatted datetime string based on specified format
38  - Supports multiple format types including standard, Japanese, and ISO formats
39 
40## Usage with Claude Desktop App
41 
42Add the following to your config file:
43 
44Config file location (macOS):
45`~/Library/Application Support/Claude/claude_desktop_config.json`
46 
47```json
48{
49  "mcpServers": {
50    "mcp-datetime": {
51      "command": "uvx",
52      "args": ["mcp-datetime"]
53    }
54  }
55}
56```
57 
58## About Installation
59 
60If you need to install the package directly (e.g., for development or source code inspection), you can use one of these methods:
61 
62- Install from PyPI
63 
64  ```bash
65  pip install mcp-datetime
66  ```
67 
68- Install from GitHub Source
69 
70  ```bash
71  git clone https://github.com/ZeparHyfar/mcp-datetime.git
72  cd mcp-datetime
73  pip install -e .
74  ```
75 
76- Example `claude_desktop_config.json` for manual installation
77 
78  ```json
79  {
80    "mcpServers": {
81      "mcp-datetime": {
82        "command": "python",
83        "args": ["-m", "mcp_datetime"],
84        "env": {
85          "PYTHON": "/path/to/your/python"
86        }
87      }
88    }
89  }
90  ```
91 
92  Replace "/path/to/your/python" with your actual Python interpreter path
93  > e.g., "/usr/local/bin/python3" or "/Users/username/.pyenv/versions/3.12.0/bin/python3"
94 
95## Basic Examples
96 
97- Command format
98 
99  ```
100  # Standard datetime format
101  call datetime-service.get_datetime {"format": "datetime"}
102  # Result: 2024-12-10 00:54:01
103 
104  # Japanese format
105  call datetime-service.get_datetime {"format": "datetime_jp"}
106  # Result: 2024年12月10日 00時54分01秒
107 
108  # Filename format
109  call datetime-service.get_datetime {"format": "filename_md"}
110  # Result: 20241210005401.md
111  ```
112 
113- Claude Desktop App prompt examples
114 
115  - User
116 
117    ```
118    Please tell me the current time in date_slash format
119    ```
120 
121  - Claude
122 
123    ```
124    I'll get the current date in date_slash format.
125 
126    The current date is 2024/12/12
127    ```
128 
129## Supported Formats
130 
131| Format Name  | Example                     | Description                  |
132| ------------ | --------------------------- | ---------------------------- |
133| date         | 2024-12-10                  | Standard date format         |
134| date_slash   | 2024/12/10                  | Date with slashes            |
135| date_jp      | 2024年12月10日              | Japanese date format         |
136| datetime     | 2024-12-10 00:54:01         | Standard datetime            |
137| datetime_jp  | 2024年12月10日 00時54分01秒 | Japanese datetime            |
138| datetime_t   | 2024-12-10T00:54:01         | DateTime with T separator    |
139| compact      | 20241210005401              | Compact format for IDs       |
140| compact_date | 20241210                    | Compact date only            |
141| compact_time | 005401                      | Compact time only            |
142| filename_md  | 20241210005401.md           | Markdown filename            |
143| filename_txt | 20241210005401.txt          | Text filename                |
144| filename_log | 20241210005401.log          | Log filename                 |
145| iso          | 2024-12-10T00:54:01+0900    | ISO 8601 format              |
146| iso_basic    | 20241210T005401+0900        | Basic ISO format             |
147| log          | 2024-12-10 00:54:01.123456  | Log format with microseconds |
148| log_compact  | 20241210_005401             | Compact log format           |
149| time         | 00:54:01                    | Time only                    |
150| time_jp      | 00時54分01秒                | Japanese time format         |
151 
152## Debugging
153 
154Since MCP servers run over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
155 
156- Using PyPI package
157 
158  ```
159  npx @modelcontextprotocol/inspector uvx mcp-datetime
160  ```
161 
162- Using downloaded source code from GitHub
163 
164  ```
165  git clone https://github.com/ZeparHyfar/mcp-datetime.git
166  npx @modelcontextprotocol/inspector uvx --directory ./mcp-datetime run mcp-datetime
167  ```
168 
169## License
170 
171This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
172