nut-ups-mcp/README.md

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:

sudo apt-get update
sudo apt-get install nut nut-client

On RHEL/CentOS:

sudo yum install nut nut-client

2. Configure NUT Server

Edit /etc/nut/ups.conf to add your UPS:

[myups]
    driver = usbhid-ups
    port = auto
    desc = "Main UPS"

Edit /etc/nut/upsd.conf:

LISTEN 127.0.0.1 3493

Edit /etc/nut/upsd.users (if authentication is needed):

[admin]
    password = yourpassword
    actions = SET
    instcmds = ALL

Start NUT services:

sudo systemctl start nut-server
sudo systemctl enable nut-server

Verify UPS is detected:

upsc myups

Setup

1. Install Dependencies

npm install

2. Configure Environment

cp .env.example .env

Edit .env with your NUT server details:

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

npm run build

Usage

With Claude Desktop

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

{
  "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:

npm start

Or use the helper script:

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):

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