OpenWRT SSH MCP Server

How to use

Interact with the MCP server from your client (Claude Desktop, VS Code, or any MCP-compatible tool). The server runs inside a container and communicates over MCP protocol, while SSH provides access to your physical OpenWRT router. You can perform tasks like checking system information, managing network settings, handling OpenThread components, and administering packages. Use the client to invoke the available tools to query status, execute commands on the router, install packages, or configure network services.

Typical usage patterns include starting the MCP server, validating the connection, then issuing commands through your MCP client to retrieve information or apply changes. The server enforces a whitelist of safe commands, maintains audit logs, and operates with a read-only filesystem inside the container for added security.

How to install

Prerequisites you need before installation:

# Prerequisites
# Ensure you have Python 3.10+ installed
python3 --version

# Optional: Docker if you want to run via Docker
docker --version

Step 1. Create or navigate to your project directory and set up a Python environment.

cd "c:\Users\YourName\Documents\UNAL\MCPs-OpenWRT"  # adjust to your path
python -m venv venv
# Windows example
venv\Scripts\activate
pip install -e .

Step 2. Configure SSH credentials for your OpenWRT router.

# Copy example env to actual env
copy .env.example .env
# Edit .env with your router credentials (host, user, etc.)

Step 3. Generate and deploy an SSH key for secure access to the router.

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

# Copy the public key to the router
ssh-copy-id -i ~/.ssh/openwrt_router.pub [email protected]

# Update the env to point to your key file
OPENWRT_KEY_FILE=C:\Users\YOUR_USER\.ssh\openwrt_router

Configuration and start flow

The server is designed to run as a Docker container with a ready-to-use MCP configuration. The following example shows how to wire the Docker command into your MCP client workflow.

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

Claude Desktop / VS Code configuration

Use the provided MCP configuration to run the server from your editor or desktop client. The Docker-based setup is optimized for easy integration with Claude Desktop and VS Code.

Inline snippet showing the main Docker command setup for Claude Desktop usage.

{
  "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"
      ]
    }
  }
}

Script helpers and common commands

If you use the provided helper scripts, you can manage the MCP lifecycle with simple commands.

.\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

Security and best practices

This server requires root access to the router, so you should enforce strict access controls. Prefer SSH key authentication, keep the environment file out of version control, review commands before execution, enable audit logging, and limit access from your workstation to the router.

openwrt_test_connection

Test SSH connection to the OpenWRT router to verify reachability and credentials.

openwrt_execute_command

Execute a validated raw command on the router using the SSH session, with command whitelist enforcement.

openwrt_get_system_info

Query system information such as uptime, memory usage, and CPU load from the router.

openwrt_restart_interface

Restart a network interface on the router to apply changes.

openwrt_get_wifi_status

Retrieve current WiFi status and connected clients.

openwrt_list_dhcp_leases

List DHCP leases observed by the router.

openwrt_get_firewall_rules

Display current firewall rules configured on the router.

openwrt_read_config

Read UCI configuration from a specified file on the router.

openwrt_thread_get_state

Get the current OpenThread network state.

openwrt_thread_create_network

Create a new OpenThread network with specified parameters.

openwrt_thread_get_dataset

Retrieve Thread network credentials and dataset information.

openwrt_thread_get_info

Provide complete details about the Thread network configuration.

openwrt_thread_enable_commissioner

Enable the Thread commissioner to allow new devices to join the network.

openwrt_opkg_update

Update package repositories on the OpenWRT router.

openwrt_opkg_install

Install IPK packages on the router through opkg.

openwrt_opkg_remove

Remove installed IPK packages from the router.

openwrt_opkg_list_installed

List packages currently installed on the router.

openwrt_opkg_info

Show detailed information about a specific package.

openwrt_opkg_list_available

List available packages from repositories.