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

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