# datetime-mcp-server

[中文版](./README-zh.md)

## Overview

`datetime-mcp-server` is a Model Context Protocol (MCP) server that provides a tool for getting the current date and time with customizable format.

## Features

- Get current datetime with customizable format
- Default format: `yyyy-MM-dd` (e.g., "2026-03-11")
- Supports various format placeholders: `yyyy`, `MM`, `dd`, `HH`, `mm`, `ss`
- Supports both stdio and HTTP transport modes

## Installation

```bash
# Install globally
npm install -g datetime-mcp-server

# Or run directly with npx
npx datetime-mcp-server
```

## Usage

### Command Line (stdio)

```bash
# Run with stdio (default)
npx datetime-mcp-server
```

### HTTP Server

```bash
# Run HTTP server on port 3000
TRANSPORT=http npx datetime-mcp-server

# Custom port
PORT=8080 TRANSPORT=http npx datetime-mcp-server
```

### Claude Code Integration

Add to your `~/.claude.json`:

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

## Available Tool

### get_current_datetime

Get the current date and time with custom format.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| format | string | No | `yyyy-MM-dd` | Date format string |

**Format Placeholders:**

| Placeholder | Description | Example |
|-------------|-------------|---------|
| yyyy | 4-digit year | 2026 |
| MM | 2-digit month | 01-12 |
| dd | 2-digit day | 01-31 |
| HH | 24-hour hour | 00-23 |
| mm | 2-digit minute | 00-59 |
| ss | 2-digit second | 00-59 |

**Examples:**

```json
{
  "name": "get_current_datetime",
  "arguments": {}
}
// Returns: "2026-03-11"

{
  "name": "get_current_datetime",
  "arguments": {
    "format": "yyyy-MM-dd HH:mm:ss"
  }
}
// Returns: "2026-03-11 14:30:45"

{
  "name": "get_current_datetime",
  "arguments": {
    "format": "yyyy/MM/dd HH:mm"
  }
}
// Returns: "2026/03/11 14:30"
```

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build
```

## License

MIT