openwrt-mcp

An MCP server that gives an AI assistant full administrative control of OpenWRT router(s) over SSH, with typed tools and a preview→confirm safety model.

Install

npm install && npm run build

Configure

Copy openwrt-mcp.config.example.json to openwrt-mcp.config.json and edit:

{
  "routers": {
    "home": {
      "host": "192.168.1.1",
      "port": 22,
      "username": "root",
      "auth": { "type": "key", "privateKeyPath": "~/.ssh/id_ed25519" },
      "readonly": false,
      "default": true
    }
  }
}

• Password auth: "auth": { "type": "password", "password": "${RTR_PW}" } (the ${RTR_PW} form reads the value from that environment variable).
• readonly: true hard-blocks all mutating tools on that router.

Config path override: set OPENWRT_MCP_CONFIG=/path/to/config.json.

Run / connect

Add to your MCP client (e.g. Claude Desktop / Claude Code) as a stdio server:

{
  "mcpServers": {
    "openwrt": {
      "command": "node",
      "args": ["/absolute/path/to/openwrt-mcp/dist/index.js"],
      "env": { "OPENWRT_MCP_CONFIG": "/absolute/path/to/openwrt-mcp.config.json" }
    }
  }
}

Safety model

• read tools run immediately.
• mutate / risky tools require a two-step call: the first call (without confirm: true) returns a preview (the exact commands + a uci changes diff where relevant); call again with confirm: true to execute.
• risky tools (firewall, network commit, reboot, raw shell) add a lock-out warning.

Tools

system_info, system_resources, reboot, net_interfaces, net_dhcp_leases, net_wifi_clients, net_routes, net_arp, uci_show, uci_get, uci_changes, uci_set, uci_delete, uci_revert, uci_commit, wifi_radios, wifi_set_enabled, wifi_configure, fw_list, fw_add_rule, fw_remove_rule, opkg_update, opkg_list, opkg_list_installed, opkg_install, opkg_remove, service_list, service_control, service_enabled, log_read, dmesg, run_command.