README.md
A lightweight MCP server that exposes the host OS clock as date/time tools.
datetime-mcp
A lightweight MCP server that exposes the host OS clock as date/time tools over stdio transport.
Quick Start
npx datetime-mcp
Or install globally:
npm install -g datetime-mcp
Tools
`datetime.now`
Returns the current date/time from the host OS clock.
| Parameter | Required | Description |
|---|---|---|
tz |
no | IANA timezone (e.g. America/New_York) |
{
"tz": "Australia/Perth",
"utcIso": "2026-01-22T03:30:00.000Z",
"epochMs": 1737516600000,
"human": "Thu, 22 Jan 2026, 11:30:00 AWST"
}
`datetime.parse`
Parses a date/time string and returns canonical forms.
| Parameter | Required | Description |
|---|---|---|
value |
yes | Date/time string parseable by JS Date |
tz |
no | IANA timezone for human-readable output |
{
"input": "2026-01-22",
"tz": "Australia/Perth",
"utcIso": "2026-01-22T00:00:00.000Z",
"epochMs": 1737504000000,
"human": "Thu, 22 Jan 2026, 08:00:00 AWST"
}
`datetime.health`
Returns server health metrics including monotonic time (won't jump with NTP adjustments).
{
"wallEpochMs": 1737516600000,
"monotonicMs": 12345678,
"processUptimeMs": 5000
}
Configuration
Claude Code
Add to ~/.claude/settings.json or project .mcp.json:
{
"mcpServers": {
"datetime": {
"command": "npx",
"args": ["-y", "datetime-mcp"],
"env": {
"MCP_TZ": "Australia/Perth"
}
}
}
}
Claude Desktop
Add to your Claude Desktop MCP config:
{
"mcpServers": {
"datetime": {
"command": "npx",
"args": ["-y", "datetime-mcp"],
"env": {
"MCP_TZ": "Australia/Perth"
}
}
}
}
Environment Variables
| Variable | Default | Description |
|---|---|---|
MCP_TZ |
Australia/Perth |
Default IANA timezone |
Development
pnpm install
pnpm dev # run with tsx (hot reload)
pnpm build # compile TypeScript
pnpm start # run compiled output
License
MIT
Tools (3)
datetime.nowReturns the current date/time from the host OS clock.datetime.parseParses a date/time string and returns canonical forms.datetime.healthReturns server health metrics including monotonic time.Environment Variables
MCP_TZDefault IANA timezoneConfiguration
claude_desktop_config.json
{
"mcpServers": {
"datetime": {
"command": "npx",
"args": ["-y", "datetime-mcp"],
"env": {
"MCP_TZ": "Australia/Perth"
}
}
}
}Try it
→What is the current date and time in New York?
→Convert the date string '2025-12-25' into a canonical format using the Tokyo timezone.
→Check the health status of the datetime MCP server.
→What time is it right now in UTC?