# mcp-datetime

MCP server with **10 date & time tools** for LLMs. Timezone conversion, date math, cron explanation, business days, Unix timestamps, and more. Zero dependencies beyond the MCP SDK.

## Tools

| Tool | Description |
|------|-------------|
| `now` | Current time in multiple timezones |
| `convert_timezone` | Convert between 60+ timezones (IANA, abbreviations, UTC offsets) |
| `date_math` | Add/subtract years, months, days, hours, minutes, seconds |
| `date_diff` | Difference between dates in days, hours, weeks, business days |
| `format_date` | Format dates with custom tokens (YYYY-MM-DD HH:mm:ss) |
| `unix_timestamp` | Convert between Unix timestamps and ISO 8601 |
| `business_days` | Count or add business days (excludes weekends) |
| `explain_cron` | Explain cron expressions in plain English |
| `countdown` | Time remaining/elapsed to a target date |
| `date_info` | Day of week, ISO week, quarter, leap year, day of year |

## Quick Start

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "datetime": {
      "command": "npx",
      "args": ["-y", "mcp-datetime"]
    }
  }
}
```

### Cursor / VS Code

Add to MCP settings:

```json
{
  "mcp": {
    "servers": {
      "datetime": {
        "command": "npx",
        "args": ["-y", "mcp-datetime"]
      }
    }
  }
}
```

## Supported Timezones

60+ timezones including:
- **Abbreviations**: UTC, GMT, EST, EDT, CST, CDT, MST, MDT, PST, PDT, CET, CEST, IST, JST, KST, SGT, MYT, AEST, NZST, and more
- **IANA names**: Asia/Tokyo, America/New_York, Europe/London, Australia/Sydney, etc.
- **UTC offsets**: +05:30, -08:00, +09, etc.

## Examples

**"What time is it in Tokyo and New York?"**
→ Uses `now` with `["JST", "EST"]`

**"Add 90 business days to March 1, 2026"**
→ Uses `business_days` with `operation: "add"`

**"What does `0 */6 * * *` mean?"**
→ Uses `explain_cron` → "Runs at minute 0 of every 6 hours"

**"How many days until December 25?"**
→ Uses `countdown` with target date

## Part of the MCP Tools Suite

- [mcp-devutils](https://www.npmjs.com/package/mcp-devutils) — 19 developer utility tools
- [mcp-apitools](https://www.npmjs.com/package/mcp-apitools) — 7 API & HTTP tools
- [mcp-texttools](https://www.npmjs.com/package/mcp-texttools) — 8 text processing tools
- [mcp-mathtools](https://www.npmjs.com/package/mcp-mathtools) — 12 math & statistics tools
- **mcp-datetime** — 10 date & time tools ← you are here
- [mcp-quick-calc](https://www.npmjs.com/package/mcp-quick-calc) — 5 calculator tools: currency conversion, percentages, compound interest, unit conversion, loan payments
- [readmecraft](https://www.npmjs.com/package/readmecraft) — README generator

- **[mcp-all-tools](https://www.npmjs.com/package/mcp-all-tools)** — All 60+ tools in a single MCP server

**60+ MCP tools** across 7 packages. Install any combination you need.

## Like this? Try mcp-devutils

**[mcp-devutils](https://www.npmjs.com/package/mcp-devutils)** — 44 developer tools in one MCP server. UUID, hash, JWT, JSON diff, AES encryption, and more. 15 free, [unlock all 44 for $5](https://buy.stripe.com/bJe00jgjugyr5Fi5cv9Zm05).

## License

MIT

## Support

If this tool saves you time, consider supporting development:

- [Buy me a coffee](https://buymeacoffee.com/gl89tu25lp)
- [Tip via Stripe ($3)](https://buy.stripe.com/dRm8wP8R295Z9VyeN59Zm00)