# NUT UPS MCP Server

An MCP (Model Context Protocol) server that enables LLMs to interact with UPS (Uninterruptible Power Supply) devices through Network UPS Tools (NUT).

## Features

- **list_ups** - List all available UPS devices
- **get_ups_status** - Get comprehensive status of a UPS (battery, load, runtime, voltage, etc.)
- **get_ups_var** - Get specific variable from UPS
- **list_ups_commands** - List available instant commands
- **execute_ups_command** - Execute instant commands (battery test, beeper control, etc.)
- **get_ups_description** - Get UPS model and manufacturer information

## Prerequisites

### 1. Install Network UPS Tools (NUT)

**On Debian/Ubuntu:**
```bash
sudo apt-get update
sudo apt-get install nut nut-client
```

**On RHEL/CentOS:**
```bash
sudo yum install nut nut-client
```

### 2. Configure NUT Server

Edit `/etc/nut/ups.conf` to add your UPS:
```ini
[myups]
    driver = usbhid-ups
    port = auto
    desc = "Main UPS"
```

Edit `/etc/nut/upsd.conf`:
```ini
LISTEN 127.0.0.1 3493
```

Edit `/etc/nut/upsd.users` (if authentication is needed):
```ini
[admin]
    password = yourpassword
    actions = SET
    instcmds = ALL
```

Start NUT services:
```bash
sudo systemctl start nut-server
sudo systemctl enable nut-server
```

Verify UPS is detected:
```bash
upsc myups
```

## Setup

### 1. Install Dependencies

```bash
npm install
```

### 2. Configure Environment

```bash
cp .env.example .env
```

Edit `.env` with your NUT server details:

```env
NUT_HOST=localhost
NUT_PORT=3493
NUT_USERNAME=admin
NUT_PASSWORD=yourpassword
```

> **Note:** Username and password are optional. Leave empty if your NUT server doesn't require authentication.

### 3. Build the Project

```bash
npm run build
```

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration (`~/.config/Claude/claude_desktop_config.json` on Linux):

```json
{
  "mcpServers": {
    "nut-ups": {
      "command": "node",
      "args": ["/home/wartana/myApp/nut-ups-mcp/dist/index.js"],
      "env": {
        "NUT_HOST": "localhost",
        "NUT_PORT": "3493",
        "NUT_USERNAME": "admin",
        "NUT_PASSWORD": "yourpassword"
      }
    }
  }
}
```

### With Other MCP Clients

Run the server directly:

```bash
npm start
```

Or use the helper script:

```bash
chmod +x run_server.sh
./run_server.sh
```

The server communicates via stdio using the MCP protocol.

## Example Commands

Once connected, you can ask the LLM things like:

- "List all UPS devices"
- "What's the battery charge level of myups?"
- "Show me the complete status of the UPS"
- "What's the current load on the UPS?"
- "How much runtime is remaining?"
- "What commands are available for this UPS?"
- "Mute the UPS beeper"
- "Start a battery test"
- "What's the input voltage?"
- "Show me the UPS model and manufacturer"

## Common UPS Variables

- `battery.charge` - Battery charge level (%)
- `battery.runtime` - Estimated runtime remaining (seconds)
- `battery.voltage` - Battery voltage
- `input.voltage` - Input line voltage
- `output.voltage` - Output voltage
- `ups.load` - UPS load (%)
- `ups.status` - UPS status (OL=Online, OB=On Battery, LB=Low Battery)
- `ups.temperature` - UPS temperature

## Common UPS Commands

- `test.battery.start` - Start battery test
- `test.battery.stop` - Stop battery test
- `beeper.mute` - Mute the beeper
- `beeper.enable` - Enable the beeper
- `load.off` - Turn off the load
- `load.on` - Turn on the load

> **Warning:** Use instant commands with caution! Commands like `load.off` will power down connected devices.

## Development

Watch mode for TypeScript (auto-recompile on changes):

```bash
npm run dev
```

## Troubleshooting

### "Error: connect ECONNREFUSED"
- Make sure NUT server (upsd) is running: `sudo systemctl status nut-server`
- Check that NUT is listening on the correct port: `netstat -tlnp | grep 3493`

### "Error: Not connected to NUT server"
- Verify NUT_HOST and NUT_PORT are correctly set
- Test connection manually: `upsc -l localhost`

### "Access Denied" errors
- Check NUT_USERNAME and NUT_PASSWORD are correct
- Verify user permissions in `/etc/nut/upsd.users`

### No UPS devices listed
- Check UPS is detected by NUT: `upsc -l`
- Verify UPS configuration in `/etc/nut/ups.conf`
- Check NUT driver is running: `sudo systemctl status nut-driver`

## License

MIT