Which integrations are available for this server?

Enables remote management of OpenWrt routers via SSH, providing tools for system monitoring, network configuration, WiFi management, firewall rules, DHCP leases, package management with opkg, and OpenThread Border Router configuration for Thread/Matter networks.

How do I use OpenWRT SSH MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OpenWRT SSH MCP Server show me the current WiFi status and connected clients" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

OpenWRT SSH MCP Server 🐳

Status Docker Python MCP

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

OpenWRT SSH MCP Server