201 lines
4.2 KiB
Markdown
201 lines
4.2 KiB
Markdown
# 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
|