OpenWRT-MCP

Read-only MCP (Model Context Protocol) server for OpenWRT router management and diagnostics. Enables AI assistants (Claude Desktop, LibreChat, Cline) to observe and analyze an OpenWRT router without any write access.

Ports

Verify

# Health check
curl http://localhost:9094/health

# List all MCP tools
curl http://localhost:9096/api/tools

# Call a tool
curl -X POST http://localhost:9096/api/tools/get_router_info \
  -H "Content-Type: application/json" \
  -d '{}'

# Get tool manifest
curl http://localhost:9096/api/tools/get_router_info/manifest

Available Tools (24)

Tools are categorized by risk level: [READ] tools are safe — they query the router with no side effects. [WRITE] tools can modify router state and require ENABLE_WRITE_OPERATIONS=1 in .env. [DESTRUCTIVE] tools are irreversible (reboot) and require explicit confirmation.

Security Model

• Read-only by default — All SSH commands are whitelisted; write operations (uci set, ifdown, ubus reboot) require ENABLE_WRITE_OPERATIONS=1
• Command whitelist — Explicit read-only patterns (ubus call, uci show, cat /proc/*, logread, ping, and others)
• Write command whitelist — Separate execute_write() path for write operations (ifdown, ifup, uci set/commit, /etc/init.d/network, ubus reboot)
• Blocked patterns — rm, reboot, wget, curl, uci set (in read path), shell metacharacters (;, |, &&, $, and others)
• Key-based authentication — Password login discouraged
• SSH host key verification — Optional via OPENWRT_KNOWN_HOSTS (set to path of known_hosts file)
• Audit logging — All commands logged with timestamps for accountability
• Localhost binding — All ports bind to 127.0.0.1 by default; set MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 for Docker

Standards Compliance

This server follows two AI-First standards:

Compliance level: L3-ready (all L1-L3 rules met; Risk Consistency Matrix enforced by automated tests).

Testing

pip install -e ".[dev]"
pytest tests/unit/ tests/integration/ -q       # 268 tests (requires .env for integration)
pytest tests/unit/ --cov=openwrt_mcp -q         # 80%+ coverage
ruff check . && ruff format --check .           # lint
mypy src/openwrt_mcp/ --strict                  # type check
bandit -r src/openwrt_mcp/ -ll                  # security

Quick Reference

License

MIT

Requirements

• Python 3.14+ (for local use) or Docker
• OpenWRT router with SSH enabled (Dropbear or OpenSSH)
• SSH key pair for authentication

Quick Start

1. Generate SSH Key

ssh-keygen -t ed25519 -f openwrt_id_ed25519 -C "openwrt-mcp"
ssh-copy-id -i openwrt_id_ed25519.pub root@192.168.0.1

2. Configure

cp .env.example .env
# Edit .env with your OPENWRT_HOST and SSH key path

3. Run with Docker

Option A — with docker compose:

# After editing .env, for Docker add MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 to .env
docker compose up -d

Option B — with plain docker run:

docker run -d \
  --name openwrt-mcp \
  -p 9094:9094 \
  -p 9095:9095 \
  -p 9096:9096 \
  -e OPENWRT_HOST=192.168.0.1 \
  -e OPENWRT_SSH_KEY=/app/keys/openwrt_id_ed25519 \
  -e MCP_UNSAFE_PUBLIC_ACCESS_CONFIRMED=1 \
  -v $(pwd)/keys:/app/keys:ro \
  ghcr.io/paulomac1000/openwrt-mcp:latest

Building locally:

git clone https://github.com/paulomac1000/openwrt-mcp.git
cd openwrt-mcp
docker build -t openwrt-mcp .
# Then run with the same docker run command above

4. Run locally (Python 3.14+)

pip install -e ".[dev]"
OPENWRT_HOST=192.168.0.1 OPENWRT_SSH_KEY=/path/to/key openwrt-mcp

Configuration

All configuration is via environment variables. See .env.example for a complete template.

Required

Optional