router-mcp

A Model Context Protocol (MCP) server + CLI that lets an AI assistant (Claude, or any MCP client) monitor and control your WiFi router — list connected devices, inspect WiFi networks, check WAN status, change SSIDs, reboot, and more.

Published as @subashgautam/router-mcp. After a global install the CLI command is just router-mcp.

Built on @modelcontextprotocol/sdk. Designed around pluggable adapters, so it can target any router family. It ships with:

• openwrt — talks to OpenWrt (and most derivatives) over SSH using ubus / uci.
• mock — realistic fake data so you can try everything with no hardware.

It is also a normal TypeScript/JavaScript library you can import.

---

Features

• 🔌 MCP server — exposes router operations as MCP tools to any MCP client.
• 🖥️ CLI — drive your router straight from the terminal (router-mcp devices, status, wifi, ...).
• 🧩 Pluggable adapters — add a new router backend by implementing one interface.
• 🔒 Safe by default — read-only unless you explicitly opt in to writes (--allow-write) and raw command execution (--allow-exec).
• 📦 Library + CLI — import { OpenWrtAdapter } from "@subashgautam/router-mcp" or run the binary.

---

Install

# Use immediately with no install
npx @subashgautam/router-mcp status --adapter mock

# Or install globally for the CLI (provides the `router-mcp` command)
npm install -g @subashgautam/router-mcp

# Or as a project dependency (library use)
npm install @subashgautam/router-mcp

Requires Node.js >= 18.

---

Quick start

1. Try it with no hardware (mock adapter)

npx @subashgautam/router-mcp status   --adapter mock
npx @subashgautam/router-mcp devices  --adapter mock
npx @subashgautam/router-mcp wifi     --adapter mock

Tip: after npm install -g @subashgautam/router-mcp you can drop the npx @subashgautam/ prefix and just run router-mcp status etc.

2. Point it at a real OpenWrt router

# Prefer the env var (or --key) so the password isn't visible in the process list:
ROUTER_HOST=192.168.1.1 ROUTER_USER=root ROUTER_PASSWORD='yourpass' npx @subashgautam/router-mcp devices

# --password also works, but see the security note below.
npx @subashgautam/router-mcp devices --host 192.168.1.1 --user root --password 'yourpass'

3. Use it as an MCP server (Claude Desktop, etc.)

Add to your MCP client config (see examples/claude_desktop_config.json):

{
  "mcpServers": {
    "router": {
      "command": "npx",
      "args": ["-y", "@subashgautam/router-mcp", "serve"],
      "env": {
        "ROUTER_ADAPTER": "openwrt",
        "ROUTER_HOST": "192.168.1.1",
        "ROUTER_USER": "root",
        "ROUTER_PASSWORD": "your-router-password",
        "ROUTER_ALLOW_WRITE": "1"
      }
    }
  }
}

Then ask your assistant things like "which devices are connected to my router?" or "rename my 2.4GHz WiFi to HomeNet".

---

MCP tools

Tool	Permission	Description
router_status	read	Model, firmware, hostname, uptime, load, memory.
list_devices	read	Connected/known clients: MAC, IP, hostname, signal, interface.
list_wifi_networks	read	Configured SSIDs with id, state, channel, band, encryption.
wan_info	read	WAN/upstream: up state, protocol, public IP, gateway, uptime.
set_wifi	write	Change an SSID's name, password, channel, or enabled state.
reboot_router	write	Reboot the router (requires confirm: true).
run_command	exec	Run a raw shell command on the router.

Write tools appear only when the server is started with --allow-write; run_command only with --allow-exec.

---

CLI reference

router-mcp [serve] [options]      Start the MCP server over stdio (default)
router-mcp <command> [options]    Run a command directly against the router

Commands:
  serve            Run the MCP server (stdio). Default when no command given.
  status           Show router model, firmware, uptime, load, memory.
  devices          List connected/known devices.
  wifi             List configured WiFi networks.
  wan              Show WAN/upstream connection info.
  reboot           Reboot the router (needs --allow-write).
  exec "<cmd>"     Run a raw shell command on the router (needs --allow-exec).

Options:
  --adapter <openwrt|mock>   Default: openwrt if --host given, else mock.
  --host --port --user --password --key --wan-iface
  --allow-write  --allow-exec  --json  -h/--help  -v/--version

Environment variables

ROUTER_ADAPTER, ROUTER_HOST, ROUTER_PORT, ROUTER_USER, ROUTER_PASSWORD, ROUTER_KEY, ROUTER_WAN_IFACE, ROUTER_ALLOW_WRITE, ROUTER_ALLOW_EXEC.

---

Library usage

import { OpenWrtAdapter, startStdioServer } from "@subashgautam/router-mcp";

// Use an adapter directly
const router = new OpenWrtAdapter({ host: "192.168.1.1", password: "..." });
console.log(await router.getStatus());
console.log(await router.listDevices());
await router.close();

// Or start a full MCP server programmatically
await startStdioServer({ adapter: "openwrt", host: "192.168.1.1", password: "...", allowWrite: true });

---

Writing a custom adapter

Implement the RouterAdapter interface and pass an instance to buildServer:

import { buildServer, type RouterAdapter } from "@subashgautam/router-mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

class MyRouterAdapter implements RouterAdapter {
  readonly name = "myrouter";
  async getStatus() { /* ... */ return {}; }
  async listDevices() { return []; }
  async getWifiNetworks() { return []; }
  async getWanInfo() { return {}; }
  async setWifi() { /* ... */ }
  async reboot() { /* ... */ }
}

const server = buildServer({
  adapter: new MyRouterAdapter(),
  config: { allowWrite: true, allowExec: false },
});
await server.connect(new StdioServerTransport());

---

Security notes

• The server is read-only by default. Enabling --allow-write / --allow-exec lets an AI client change settings or run commands on your router — only enable what you need.
• Avoid --password on the command line — process arguments are world-readable on most systems (ps aux, /proc/<pid>/cmdline), so the password leaks to other local users. Prefer key-based SSH auth (--key) or the ROUTER_PASSWORD environment variable.
• run_command is powerful; treat it like giving shell access. It is only available with --allow-exec.
• Wifi network ids passed to set_wifi are validated against the uci section-name charset ([A-Za-z0-9_]) before use, so a malicious id cannot inject shell commands.

---

License

MIT © SwiftTech