Datetimeday

A lightweight MCP server for date, time, and day of week.

Installation

pip install mcp-datetimeday

Or with uv:

uv pip install mcp-datetimeday

Usage

The server supports two transport modes: stdio (default) for Claude Desktop, and streamable-http for Claude Code or any HTTP-based MCP client.

Claude Code (HTTP — recommended)

Run the server as a persistent HTTP process (e.g., via PM2), then register it:

# Start the server
mcp-datetimeday --transport streamable-http --port 8105

# Register in Claude Code (user scope)
claude mcp add --transport http --scope user mcp-datetimeday http://127.0.0.1:8105/mcp

Claude Code (stdio)

claude mcp add --scope user mcp-datetimeday -- uvx mcp-datetimeday

Claude Desktop

Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json):

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

CLI Options

--transport {stdio,streamable-http}   Transport protocol (default: stdio)
--port PORT                           Port for HTTP transport (default: 8105)
--host HOST                           Host for HTTP transport (default: 127.0.0.1)

PM2 (persistent HTTP server)

An ecosystem.config.cjs is included for PM2:

pm2 start ecosystem.config.cjs
pm2 save

Available Tools

Tool	Description
get_datetime	Get current date/time with day of week first. Supports tz arg for timezone, format arg: iso8601, unix, human, or full (default).
relative_time	Get relative time between dates (e.g., "3 days ago", "in 2 weeks")
days_in_month	Get number of days in a month with first/last day info
convert_time	Convert time between timezones
get_week_year	Get week number, ISO week, day of year, quarter

Example Output

get_datetime()

{
  "day_of_week": "Monday",
  "date": "2026-02-02",
  "time": "16:55:22",
  "timezone": "PST",
  "utc_offset": "-0800",
  "iso8601": "2026-02-02T16:55:22-08:00",
  "unix_timestamp": 1770080122,
  "human_readable": "Monday, February 02, 2026 at 04:55 PM"
}

get_datetime(format="iso8601")

{
  "day_of_week": "Monday",
  "iso8601": "2026-02-02T16:55:22-08:00"
}

get_datetime(tz="UTC")

{
  "day_of_week": "Tuesday",
  "date": "2026-02-03",
  "time": "00:55:22",
  "timezone": "UTC",
  "utc_offset": "+0000",
  "iso8601": "2026-02-03T00:55:22+00:00",
  "unix_timestamp": 1738544122,
  "human_readable": "Tuesday, February 03, 2026 at 12:55 AM"
}

relative_time("2026-02-10")

{
  "target": "2026-02-10",
  "target_day_of_week": "Tuesday",
  "reference": "now",
  "relative": "in 1 week",
  "days_difference": 7,
  "total_seconds": 604800
}

get_week_year()

{
  "date": "2026-02-02",
  "day_of_week": "Monday",
  "day_of_week_number": 1,
  "week_number": 5,
  "iso_week": 6,
  "iso_year": 2026,
  "day_of_year": 33,
  "days_remaining_in_year": 332,
  "is_weekend": false,
  "quarter": 1
}

Development

git clone https://github.com/cfdude/mcp-datetimeday.git
cd mcp-datetimeday
uv sync
uv run mcp-datetimeday