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
🛠️ 19 OpenWRT Tools - Complete router management (network, system, Thread, packages)
🚀 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

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

💬 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:

Fork the project
Create a branch for your feature
Commit your changes
Push to the branch
Open a Pull Request

📖 Resources

📄 License

MIT

Made with ❤️ for the OpenWRT and MCP community