OpenWRT SSH MCP Server 🐳

A containerized MCP (Model Context Protocol) server for managing OpenWRT routers via SSH. This server allows AI agents (like Claude) to execute commands and manage OpenWRT routers remotely and securely.

🎉 STATUS: ✅ Fully functional and tested with physical router

✨ Features

• 🐳 Docker Ready - Optimized image with multi-stage build (271MB)

• 🔐 Robust Security - Command whitelist, read-only filesystem, audit logging

• 🛠️ 23 OpenWRT Tools - Complete router management (network, system, Thread, packages, firmware OTA)

• 🚀 Easy Integration - Compatible with Claude Desktop and VS Code

• 📊 Monitoring - Detailed logs of all operations

• 🔄 MCP Toolkit - Fully compatible with Docker Desktop MCP

• 📦 Package Management - Install/remove IPK packages with opkg

• 🔗 OpenThread OTBR - Support for Thread Border Router

Related MCP server: remote-admin-mcp

Architecture

┌─────────────────────┐
│ Claude / VS Code    │  ← Your AI agent
└──────────┬──────────┘
           │ MCP Protocol (stdio)
           │
┌──────────▼──────────┐
│ Docker Container    │  ← MCP Server
│  ┌──────────────┐   │
│  │ MCP Server   │   │
│  │ (Python)     │   │
│  └──────┬───────┘   │
└─────────┼───────────┘
          │ SSH
          │
┌─────────▼───────────┐
│ OpenWRT Router      │  ← Your physical router
│ (192.168.1.1)       │
└─────────────────────┘

Features

• 🔐 Secure SSH authentication (password or key-based)

• 🛠️ OpenWRT-specific tools (ubus, uci)

• ✅ Command validation with whitelist

• 📝 Audit logging

• 🐳 Docker support (optional)

• 🔌 Integration with Claude Desktop and VS Code

Requirements

• Python 3.10+

• OpenWRT router with SSH enabled

• SSH access to router (root user recommended)

Installation

1. Clone or create the project

cd "c:\Users\Luis Antonio\Documents\UNAL\MCPs-OpenWRT"

2. Create virtual environment and install dependencies

python -m venv venv
.\venv\Scripts\activate  # Windows
pip install -e .

3. Configure SSH credentials

# Copy example file
copy .env.example .env

# Edit .env with your router credentials

4. Generate and copy SSH key (recommended)

# Generate dedicated key
ssh-keygen -t ed25519 -f ~/.ssh/openwrt_router -C "MCP Server"

# Copy to router
ssh-copy-id -i ~/.ssh/openwrt_router.pub root@192.168.1.1

# Update .env
OPENWRT_KEY_FILE=C:\Users\YOUR_USER\.ssh\openwrt_router

🔧 Configuration

Claude Desktop (Docker)

Includes optimized configuration in claude_desktop_config.json:

{
  "mcpServers": {
    "openwrt-router-docker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network", "host",
        "--env-file", "C:\\Users\\Luis Antonio\\Documents\\UNAL\\MCPs-OpenWRT\\.env",
        "--mount", "type=bind,src=C:\\Users\\Luis Antonio\\.ssh,dst=/root/.ssh,readonly",
        "openwrt-ssh-mcp:latest"
      ]
    }
  }
}

VS Code with GitHub Copilot

The project includes complete VS Code configuration:

Option 1: Direct Python (Recommended)

# Open workspace
code mcp-openwrt.code-workspace

# In Copilot Chat (Ctrl+Shift+I):
"What OpenWRT tools do I have available?"

Option 2: With Tasks

Terminal > Run Task > "Start MCP Server (Python)"

Option 3: Startup Script

.\start-mcp-vscode.ps1

Script Helper

Use docker-mcp.ps1 for all operations:

.\docker-mcp.ps1 build   # Build image
.\docker-mcp.ps1 run     # Run server
.\docker-mcp.ps1 test    # Test connection
.\docker-mcp.ps1 logs    # View logs
.\docker-mcp.ps1 shell   # Open shell
.\docker-mcp.ps1 clean   # Clean all

🛠️ Available Tools

System & Network (8 tools)

• openwrt_test_connection - Test SSH connection

• openwrt_execute_command - Execute raw command (validated)

• openwrt_get_system_info - System info (uptime, memory, CPU)

• openwrt_restart_interface - Restart network interface

• openwrt_get_wifi_status - WiFi status and clients

• openwrt_list_dhcp_leases - List DHCP clients

• openwrt_get_firewall_rules - View firewall rules

• openwrt_read_config - Read UCI config file

OpenThread Border Router (5 tools)

• openwrt_thread_get_state - Current Thread state

• openwrt_thread_create_network - Create new Thread network

• openwrt_thread_get_dataset - Get network credentials

• openwrt_thread_get_info - Complete Thread network info

• openwrt_thread_enable_commissioner - Allow new devices

Package Management (6 tools)

• openwrt_opkg_update - Update package lists

• openwrt_opkg_install - Install IPK packages

• openwrt_opkg_remove - Remove packages

• openwrt_opkg_list_installed - List installed packages

• openwrt_opkg_info - Detailed package info

• openwrt_opkg_list_available - List available packages

Firmware OTA (4 tools)

• openwrt_firmware_version - Current firmware version, board model, release info

• openwrt_firmware_upload - SCP a local .img/.bin to /tmp/firmware.img with SHA256 check

• openwrt_firmware_verify - sysupgrade -T to validate without flashing

• openwrt_firmware_flash - Flash via sysupgrade with optional keep_settings (clean install when false)

💬 Usage Examples

Once configured, you can ask Claude:

System & Network

• "Show me the WiFi status on my router"

• "List connected devices"

• "Restart the wan interface"

• "What's the router's memory usage?"

Package Management

• "Update the package repositories"

• "Install the luci-app-openthread package"

• "Show me installed packages"

• "Give me information about the ot-br-posix package"

OpenThread

• "Create a Thread network called 'MyHome' on channel 15"

• "Show me the Thread network status"

• "Enable the commissioner to add new devices"

• "Give me the Thread network credentials"

Security

⚠️ IMPORTANT: This server has root access to your router. Make sure to:

• Use SSH key authentication (not password)

• Keep .env out of version control

• Review commands before production execution

• Enable audit logging

• Limit SSH access from router to your PC

📚 Documentation

🚀 Quick Start

• QUICKSTART_DOCKER.md - Quick start with Docker

• TEST_OPKG.md - Test IPK package management

📖 Detailed Guides

• DOCKER_GUIDE.md - Complete Docker guide

🧪 Testing

# Test with helper script
.\docker-mcp.ps1 test

# Test with MCP Inspector
npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector docker run -i --rm openwrt-ssh-mcp:latest

# View logs
.\docker-mcp.ps1 logs

🔐 Implemented Security

• ✅ Read-only filesystem - Immutable container

• ✅ No capabilities - No special permissions

• ✅ SSH keys read-only - Protected keys

• ✅ Command whitelist - Only safe commands

• ✅ Audit logging - Complete logging

• ✅ Volatile tmpfs - /tmp cleaned on restart

• ✅ No privilege escalation - No sudo

🎯 Use Cases

Advanced Workflows

• 🔄 Automated backup of UCI configurations

• 📊 Network monitoring - Connected devices, resource usage

• 🔧 AI-guided troubleshooting

• 📝 Automatic documentation of changes

• 🚨 Network anomaly alerts

• 📦 Package management - Install/update software

• 🔗 Thread configuration - Create and manage Thread/Matter networks

• 🛡️ Security auditing - Review firewall rules

🐳 Docker Hub (Optional)

# Publish your image
docker login
docker tag openwrt-ssh-mcp:latest yourusername/openwrt-ssh-mcp:latest
docker push yourusername/openwrt-ssh-mcp:latest

🛠️ Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
ruff check --fix .

# Rebuild after changes
.\docker-mcp.ps1 build

🤝 Contributing

Contributions are welcome! Please:

1. Fork the project

2. Create a branch for your feature

3. Commit your changes

4. Push to the branch

5. Open a Pull Request

📖 Resources

• MCP Documentation

• Docker MCP Blog

• OpenWRT Documentation

• MCP Servers Repository

📄 License

MIT

Made with ❤️ for the OpenWRT and MCP community