<p align="center">
  <img src="icon.png" width="96" height="96" alt="Dell iDRAC MCP icon">
</p>

# Dell iDRAC MCP

[![CI](https://github.com/mbgroen/dell-idrac-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mbgroen/dell-idrac-mcp/actions/workflows/ci.yml)
[![Latest release](https://img.shields.io/github/v/release/mbgroen/dell-idrac-mcp?sort=semver)](https://github.com/mbgroen/dell-idrac-mcp/releases/latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) server for the **Dell iDRAC 8**, the out-of-band management controller in 13th-generation PowerEdge servers (T430, T630, R430, R530, R630, R730, R730xd, ...). It lets an AI assistant answer questions about your server's hardware and health, and, if you allow it, power it on, restart it or change BIOS settings.

It talks directly to the iDRAC's **Redfish API** over your local network. There is no cloud service, no Dell account and no agent on the server. It works even when the operating system is down or the server is off.

Ships as a one-click **`.mcpb` extension for Claude Desktop**, and runs as a plain Node.js server for any other MCP client.

> This is an independent community project. It is not affiliated with or endorsed by Dell Technologies.

---

## What you can ask

> *Is my server healthy? Anything I should worry about?*
> *How warm is it inside, and how fast are the fans spinning?*
> *How much power is the server drawing right now, and what was the peak?*
> *Are any of my disks predicted to fail? What RAID level is the data volume?*
> *What happened on the server last night? Show me the event log.*
> *Which firmware versions are installed, and is the iDRAC firmware current?*
> *Is virtualization enabled in the BIOS?*
> *Shut the server down cleanly and tell me when it's off.* (needs operator mode)
> *Boot from the network once and restart.* (needs operator mode)
> *Turn on the identify LED so I can find the machine.* (needs operator mode)

## Highlights

- **Health at a glance**: one call checks CPUs, memory, fans, temperatures, power supplies, voltages, RAID controllers, disks and volumes, and reports only what needs attention, together with recent warnings from the event log.
- **Full inventory**: processors, DIMMs, disks with predicted failure and SSD wear, virtual disks, network ports, iDRAC network settings and services, and firmware versions of every component.
- **Logs and jobs**: the System Event Log and the Lifecycle Controller log, newest first, filterable by severity or text, and the iDRAC job queue.
- **Settings**: BIOS attributes with their allowed values and help text, boot mode and boot order, virtual media, and a full Server Configuration Profile export.
- **Safe by default**: three permission modes that mirror the iDRAC roles. Read-only is the default; tools you have not enabled are never even listed.
- **Kind to the iDRAC**: one Redfish session per run (no login entry in the Lifecycle log for every request), logout on exit, limited concurrency for the slow iDRAC 8, and no retry loop on a wrong password, so you cannot lock yourself out.
- **Built on real hardware**: developed and tested against a PowerEdge T430 running the final iDRAC 8 firmware, including its Redfish quirks (the one `$expand` syntax it accepts, log service ids that differ from their URIs, ports that are listed but missing).
- **Escape hatch**: `idrac_get` reads any Redfish resource; `idrac_raw_request` (admin) sends anything.

---

## Requirements

- A Dell PowerEdge server with **iDRAC 8**, firmware **2.40 or newer**. 2.70 or newer is recommended; **2.86.86.86** is the final iDRAC 8 release.
- The iDRAC must be reachable over HTTPS (port 443) from the computer running the MCP client.
- Redfish enabled on the iDRAC. It is on by default (*iDRAC Settings → Services → Redfish*).
- Any iDRAC license works (Basic, Express or Enterprise). Virtual media requires Enterprise.
- Node.js 20 or newer, only for the npx or source install. The `.mcpb` extension uses the runtime built into Claude Desktop.

---

## Install

### Option A — Claude Desktop extension (`.mcpb`)

1. Download `dell-idrac-mcp-<version>.mcpb` from the [latest release](https://github.com/mbgroen/dell-idrac-mcp/releases/latest).
2. Double-click the file, or open Claude Desktop → **Settings → Extensions** and drag it in.
3. Fill in the iDRAC address, user name and password, and choose whether to allow actions or configuration changes.
4. Start a new chat and ask *"Is my server healthy?"*

Everything is bundled into one file, so no separate Node.js installation is needed.

> The `npx` examples below use the npm package. Until it is published to npm you can point npx straight at the repository instead: `npx -y github:mbgroen/dell-idrac-mcp`.

### Option B — Claude Code

```bash
claude mcp add dell-idrac --scope user \
  --env IDRAC_HOST=192.168.0.80 \
  --env IDRAC_USERNAME=claude \
  --env IDRAC_PASSWORD='your-password' \
  -- npx -y @mbgroen/dell-idrac-mcp
```

### Option C — any other MCP client

Add this to the client's MCP server configuration (Cursor, VS Code, Windsurf, Zed, custom hosts):

```json
{
  "mcpServers": {
    "dell-idrac": {
      "command": "npx",
      "args": ["-y", "@mbgroen/dell-idrac-mcp"],
      "env": {
        "IDRAC_HOST": "192.168.0.80",
        "IDRAC_USERNAME": "claude",
        "IDRAC_PASSWORD": "your-password",
        "IDRAC_PERMISSION_MODE": "read-only"
      }
    }
  }
}
```

### Option D — from source

```bash
git clone https://github.com/mbgroen/dell-idrac-mcp.git
cd dell-idrac-mcp
npm install            # also compiles TypeScript
cp .env.example .env   # fill in host, user and password
npm run test:live      # optional: read-only check against your iDRAC
node dist/index.js     # speaks MCP over stdio
```

---

## Create a dedicated iDRAC user

You can use `root`, but a dedicated account limits what the assistant can do even if this server's own checks were bypassed, and it makes the assistant's activity easy to recognise in the Lifecycle log.

1. Open the iDRAC web interface and go to **iDRAC Settings → User Authentication → Local Users**.
2. Click a free user ID and choose **Configure User**.
3. Enter a user name (for example `claude`) and a strong password, and enable the user.
4. Under **iDRAC User Privileges**, pick the role that matches the permission mode you plan to use:

| Permission mode | iDRAC role | Why |
| --- | --- | --- |
| `read-only` | **Read Only** | Login is all that reading needs. |
| `operator` | **Operator** | Server control (power, LED) and configure privileges. |
| `admin` | **Administrator** | Clearing logs and some configuration changes need it. |

IPMI and serial-over-LAN privileges are not used and can stay at *No Access*. The iDRAC enforces its own privileges as well: if a tool fails with HTTP 403, the account lacks a privilege for that operation.

---

## Permission modes

The server only lists the tools its mode allows, and checks the mode again on every call.

| Mode | `IDRAC_PERMISSION_MODE` | Extension toggle | What it adds |
| --- | --- | --- | --- |
| Read-only (default) | `read-only` | both off | Inventory, health, sensors, logs, jobs, BIOS/boot/virtual media settings, configuration export. Nothing can change. |
| Operator | `operator` | *Allow power control and other actions* | Power on, graceful shutdown or restart, force off, power cycle, NMI; identify LED; one-time boot device; attach or detach virtual media; restart the iDRAC; delete jobs. |
| Admin | `admin` | *Allow configuration changes* | Change BIOS settings (staged in a configuration job), clear the System Event Log, raw Redfish write requests. |

Start with read-only. A power action affects everything that runs on the server: the assistant is instructed to confirm before turning it off or restarting it, and Claude Desktop asks for your approval before each tool call unless you turn that off.

---

## Tools

### Read-only

| Tool | What it does |
| --- | --- |
| `idrac_status` | Connection check: iDRAC firmware (with a note when newer firmware exists), Redfish version, model, service tag, permission mode. Use it first when something fails. |
| `idrac_system_overview` | Model, service tag, BIOS and iDRAC versions, power state, health, CPU and memory totals, power draw and inlet temperature. |
| `idrac_health` | Checks every subsystem and lists only unhealthy components, plus recent warning and critical events. |
| `idrac_thermal` | Fan speeds, temperatures with thresholds, fan redundancy. |
| `idrac_power` | Current, average, minimum and peak power, power cap, power supplies, redundancy, optionally voltages. |
| `idrac_processors` | CPUs: model, cores, threads, speed, health. |
| `idrac_memory` | DIMMs: slot, size, type, speed, manufacturer, part number, health. |
| `idrac_storage` | RAID and other controllers, physical disks (predicted failure, SSD wear), virtual disks. |
| `idrac_network_interfaces` | Server network ports (MAC, link, speed) and the iDRAC's IP configuration. |
| `idrac_firmware_inventory` | Firmware versions of all components, optionally including rollback versions. |
| `idrac_manager_info` | iDRAC firmware, time, enabled services and ports (HTTPS, SSH, IPMI, SNMP, ...), NTP, open sessions. |
| `idrac_logs` | System Event Log (`sel`) or Lifecycle log (`lclog`), newest first, filter by severity or text. |
| `idrac_list_jobs` | The iDRAC job queue, or one job by id. |
| `idrac_bios_attributes` | BIOS settings by text or name, pending changes, and (with `describe`) allowed values and help text. |
| `idrac_boot_settings` | Boot mode, boot order, one-time boot override and its allowed targets. |
| `idrac_virtual_media` | Virtual CD/removable disk state and whether attaching images is supported. |
| `idrac_export_config` | Server Configuration Profile export (XML), optionally saved to a file. Includes iDRAC settings that have no other Redfish view, such as the thermal profile. |
| `idrac_get` | GET any resource under `/redfish/v1`, with optional `$expand` and `$select`. |

### Operator

| Tool | What it does |
| --- | --- |
| `idrac_power_action` | `On`, `GracefulShutdown`, `GracefulRestart`, `ForceOff`, `ForceRestart`, `PowerCycle`, `PushPowerButton`, `Nmi`; optionally waits for the new power state. Firmware without `GracefulShutdown` gets an ACPI power-button press instead. |
| `idrac_set_identify_led` | Identify LED on, blinking or off. |
| `idrac_set_boot_override` | One-time (or continuous) boot from PXE, virtual CD, BIOS setup, ...; `None` clears it. |
| `idrac_virtual_media_insert` | Attach an ISO or image from an HTTP(S), NFS or CIFS URL, where the firmware supports it. |
| `idrac_virtual_media_eject` | Detach virtual media. |
| `idrac_reset_idrac` | Restart the iDRAC (the server keeps running). |
| `idrac_delete_job` | Remove a job from the queue, for example a scheduled BIOS change. |

### Admin

| Tool | What it does |
| --- | --- |
| `idrac_set_bios_attributes` | Validate and stage BIOS changes, create the configuration job, and apply at the next reboot or reboot now. |
| `idrac_clear_log` | Clear the System Event Log. |
| `idrac_raw_request` | Any GET, POST, PATCH or DELETE under `/redfish/v1`. |

---

## Configuration reference

All settings are environment variables. The `.mcpb` extension sets them from its settings panel.

| Variable | Default | Description |
| --- | --- | --- |
| `IDRAC_HOST` | *(required)* | Host name or IP of the iDRAC. `https://` is assumed; a port may be added (`10.0.0.5:8443`). |
| `IDRAC_USERNAME` | *(required)* | iDRAC user name. |
| `IDRAC_PASSWORD` | *(required)* | iDRAC password. |
| `IDRAC_PERMISSION_MODE` | `read-only` | `read-only`, `operator` or `admin`. |
| `IDRAC_ALLOW_ACTIONS` | `false` | `true` selects operator mode (used by the extension). |
| `IDRAC_ALLOW_CONFIG` | `false` | `true` selects admin mode (used by the extension). |
| `IDRAC_VERIFY_TLS` | `false` | Verify the iDRAC's TLS certificate. |
| `IDRAC_TIMEOUT_SECONDS` | `60` | Per-request timeout. |
| `IDRAC_AUTH_MODE` | `session` | `session` (X-Auth-Token) or `basic` (HTTP Basic on every request). |
| `IDRAC_MAX_CONCURRENCY` | `4` | Maximum parallel requests to the iDRAC. |

---

## Security notes

- The server connects only to the iDRAC you configure. Nothing is sent anywhere else.
- In Claude Desktop the password is stored by the app in your operating system's secure storage and passed to the server at start-up. The server never includes it in tool output or logs.
- The iDRAC's self-signed certificate is accepted by default; this exception applies only to this server's own connection to the iDRAC. Install a trusted certificate and enable *Verify TLS certificate* to remove it.
- A rejected login is not retried for 60 seconds, so a wrong password cannot trigger the iDRAC's IP blocking.
- iDRAC 8 no longer receives security updates. Keep it on a management network or VLAN that is not reachable from the internet.
- An assistant acts on what it reads. Log messages and asset tags come from the server itself; keep operator and admin modes off unless you need them.

See [SECURITY.md](SECURITY.md) for how to report a vulnerability.

---

## Troubleshooting

| Symptom | What to do |
| --- | --- |
| *did not return a Redfish service root* | `IDRAC_HOST` must be the iDRAC's address, not the server's OS. Check that Redfish is enabled (`racadm set iDRAC.Redfish.Enable 1`). |
| *The iDRAC rejected the credentials* | Check user name and password, and that the user is enabled. The server waits 60 seconds before trying again. |
| *EHOSTUNREACH* on macOS while `ping` works | macOS asks apps for permission to reach devices on the local network. Allow Claude under **System Settings → Privacy & Security → Local Network**, then try again. |
| Timeouts | iDRAC 8 is slow, especially just after it restarts. Raise the timeout. If the iDRAC stays unresponsive, restart it with `idrac_reset_idrac` or `racadm racreset`. |
| HTTP 404 for a resource | Older firmware exposes fewer Redfish resources. Update the iDRAC to 2.86.86.86 (iDRAC web interface → *Maintenance → System Update*). |
| HTTP 403 | The iDRAC user's role lacks a privilege for this operation. See [Create a dedicated iDRAC user](#create-a-dedicated-idrac-user). |
| No power readings | Servers with a cabled, non-redundant power supply (an option on the T430) have no power monitoring. Hot-plug power supplies report readings. |
| A power cap is shown but the server draws more | iDRAC 8 reports the configured cap value even when power capping is disabled. `idrac_power` labels it `power_cap_setting_watts`; whether capping is enabled is in *iDRAC Settings → Power Configuration* (or `ServerPwr.1#PowerCapSetting` in `idrac_export_config`). |
| Virtual media insert not supported | Older iDRAC 8 firmware exposes virtual media read-only through Redfish; 2.86 supports attaching images. Otherwise use the iDRAC web interface or `racadm remoteimage`. |
| Fan speeds cannot be changed | iDRAC 8 has no fan control through Redfish. This server only reads fan data, so it works alongside IPMI-based fan scripts. |

---

## Development

```bash
npm install
npm run build          # compile TypeScript to dist/
npm run typecheck
npm test               # smoke test + end-to-end test against a mock iDRAC 8
npm run test:live      # read-only test against the iDRAC in .env
npm run inspect        # open the MCP Inspector
npm run bundle         # build dell-idrac-mcp-<version>.mcpb
```

The mock iDRAC (`scripts/mock-idrac.mjs`) imitates an iDRAC 8 (firmware 2.86) on a PowerEdge T430: session login, `$expand`, paged logs with both orderings, actions, PATCH, an SCP export job, and the quirks of the real firmware. Run it on its own with `node scripts/mock-idrac.mjs` and point `IDRAC_HOST` at `http://127.0.0.1:8443` (user `root`, password `calvin`) to try changes without touching real hardware.

Project layout:

```
src/
  index.ts              MCP server: tool registration, permission checks, shutdown
  config.ts             environment variables and permission modes
  redfish/client.ts     HTTP client: sessions, TLS, concurrency, paging, errors
  redfish/resources.ts  resource discovery and output shaping
  tools/                tool definitions, grouped by area
scripts/                build, tests, mock iDRAC
manifest.json           Claude Desktop extension manifest (tool list synced on build)
```

### Releasing

Versions follow [semantic versioning](https://semver.org/): **major** for breaking changes, **minor** for new features, **patch** for fixes.

1. Bump `version` in `package.json` and add a section to `CHANGELOG.md`.
2. Run `npm run bundle`; it syncs the version and tool list into `manifest.json`.
3. Commit, then tag and push: `git tag -a v1.1.0 -m "v1.1.0" && git push --follow-tags`.

The release workflow runs the tests, builds the `.mcpb` and an npm tarball, and attaches both with checksums to the GitHub release. It also publishes to npm when an `NPM_TOKEN` secret is configured.

---

## Compatibility

| Controller | Servers | Status |
| --- | --- | --- |
| iDRAC 8, firmware 2.70 – 2.86 | PowerEdge 13th generation (x30) | Supported. Tested on a PowerEdge T430 with iDRAC 8 2.86.86.86. |
| iDRAC 8, firmware 2.40 – 2.6x | PowerEdge 13th generation | Should work; some resources (storage, logs, export) may be missing. |
| iDRAC 9 | PowerEdge 14th generation and later | Untested. Uses the same standard Redfish paths, so most read tools are expected to work. |
| iDRAC 7 | PowerEdge 12th generation | Not supported (very limited Redfish). |

Reports from other models and firmware versions are welcome. Please open an issue with the output of `idrac_status`.

---

## License

[MIT](LICENSE) © mbgroen

Dell, PowerEdge and iDRAC are trademarks of Dell Inc. or its subsidiaries.