Metadata-Version: 2.4
Name: mcp-datetimeday
Version: 0.1.0
Summary: A lightweight MCP server for date, time, and day of week
Project-URL: Homepage, https://github.com/cfdude/mcp-datetimeday
Project-URL: Repository, https://github.com/cfdude/mcp-datetimeday
Project-URL: Issues, https://github.com/cfdude/mcp-datetimeday/issues
Author-email: Rob Sherman <rsherman@velocityinteractive.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,date,datetime,fastmcp,mcp,time,timezone
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Description-Content-Type: text/markdown

# mcp-datetimeday

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

## Installation

```bash
uv sync
```

## Usage

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

```json
{
  "mcpServers": {
    "datetimeday": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/robsherman/Servers/mcp-datetimeday", "mcp-datetimeday"]
    }
  }
}
```

## 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()`
```json
{
  "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")`
```json
{
  "day_of_week": "Monday",
  "iso8601": "2026-02-02T16:55:22-08:00"
}
```

### `get_datetime(tz="UTC")`
```json
{
  "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")`
```json
{
  "target": "2026-02-10",
  "target_day_of_week": "Tuesday",
  "reference": "now",
  "relative": "in 1 week",
  "days_difference": 7,
  "total_seconds": 604800
}
```

### `get_week_year()`
```json
{
  "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

```bash
uv sync
uv run mcp-datetimeday
```
