home / mcp / asus merlin mcp server

ASUS Merlin MCP Server

Model Context Protocol (MCP) server for managing ASUS routers running Asuswrt-Merlin firmware via SSH/SCP.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "kcsoukup-asus-merlin-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/home/yourusername/.ssh:/home/mcpuser/.ssh:ro",
        "-e",
        "ROUTER_HOST=192.168.1.1",
        "-e",
        "ROUTER_USER=admin",
        "-e",
        "ROUTER_KEY_FILE=/home/mcpuser/.ssh/id_rsa",
        "kcsoukup/asus-merlin-mcp:latest"
      ],
      "env": {
        "ROUTER_HOST": "192.168.1.1",
        "ROUTER_USER": "admin",
        "ROUTER_KEY_FILE": "/home/mcpuser/.ssh/id_rsa"
      }
    }
  }
}

This MCP Server lets you manage ASUS routers running Asuswrt-Merlin via SSH/SCP from a centralized control point. It exposes a set of tools to monitor, configure, and automate router tasks, so you can administer firewall rules, VPN routing, DHCP reservations, NVRAM values, and more from your preferred MCP client.

How to use

You connect your MCP client to the ASUS Merlin MCP Server using the stdio (local) configuration. The server runs as a Docker container and accepts commands that map to router actions. Use the MCP client to run tool prompts such as checking system status, listing connected devices, managing DHCP reservations, filtering URLs, and controlling VPN routing.

Key usage patterns include: activating or inspecting router services, reading or writing NVRAM variables, uploading or downloading router files with integrity checks, and applying parental controls or firewall rules. Each tool is designed to be invoked by your MCP client with a clear, human-friendly prompt. When you issue a task, the MCP server connects to your router and returns structured results you can use in scripts or dashboards.

How to install

Prerequisites: you need a workstation with Docker and SSH access to your router. The router must have SSH enabled and be reachable on the network.

Step 1. Prepare SSH access to your router. Ensure SSH login is allowed and that you have a key-based authentication setup for secure access.

Step 2. Install Docker on your workstation if it is not already installed.

Step 3. Use the provided MCP configuration to run the server in Docker. The following example shows how to configure the router connection and run the container with SSH key access. Copy this configuration exactly as shown.

{
  "mcpServers": {
    "asus-router": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/yourusername/.ssh:/home/mcpuser/.ssh:ro",
        "-e", "ROUTER_HOST=192.168.1.1",
        "-e", "ROUTER_USER=admin",
        "-e", "ROUTER_KEY_FILE=/home/mcpuser/.ssh/id_rsa",
        "kcsoukup/asus-merlin-mcp:latest"
      ]
    }
  }
}

Additional configuration notes

Security-conscious users migrate to rootless containers. If you upgrade from an older version, update the container user to mcpuser and adjust the SSH key path and volume mount accordingly. Use the absolute SSH key path inside the container and ensure the SSH key is readable by the container user.

Complete MCP configuration example for v3.x safety changes. This shows the updated volume mount, environment variable, and image usage.

{
  "mcpServers": {
    "asus-router": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/yourusername/.ssh:/home/mcpuser/.ssh:ro",
        "-e", "ROUTER_HOST=192.168.1.1",
        "-e", "ROUTER_USER=admin",
        "-e", "ROUTER_KEY_FILE=/home/mcpuser/.ssh/id_rsa",
        "kcsoukup/asus-merlin-mcp:latest"
      ]
    }
  }
}

Security notes

Use SSH keys in place of passwords for better security. Keep SSH access limited to LAN unless WAN access is required. Be careful with NVRAM operations; incorrect values can corrupt the router. Always test commands manually before automating, and maintain backups of your router configuration.

Troubleshooting

If you encounter connection or permission issues, verify SSH accessibility, key permissions, and that the container user has access to the SSH key. For Docker-related problems, ensure the volume mount paths are absolute and accessible by the host running Docker.

Available tools

get_router_info

Retrieve system information such as uptime, memory, and firmware versions.

get_connected_devices

List DHCP clients currently connected to the network.

get_all_network_devices

Provide a comprehensive device list including DHCP/static/ARP entries.

get_wifi_status

Show the status of all WiFi radios and SSIDs.

restart_service

Restart a specified router service.

reboot_router

Reboot the router (requires confirmation).

get_vpn_status

Check VPN client/server status.

list_processes

List running processes on the router.

get_nvram_variable

Read a specific NVRAM variable.

set_nvram_variable

Write to an NVRAM variable.

execute_command

Run a custom command on the router.

read_file

Read a file from the router.

upload_file

Upload a file to the router with MD5 verification.

download_file

Download a file from the router with MD5 verification.

add_mac_filter

Add a MAC address to the WiFi MAC filter.

remove_mac_filter

Remove a MAC filter entry.

list_mac_filters

List current MAC filter entries.

add_dhcp_reservation

Add a static DHCP reservation for a MAC address.

remove_dhcp_reservation

Remove a DHCP reservation.

list_dhcp_reservations

List all DHCP reservations.

block_device_internet

Block or unblock a device's Internet access.

list_blocked_devices

Show devices currently blocked from Internet access.

add_vpn_routing_policy

Route a device through a VPN client.

remove_vpn_routing_policy

Remove a device from VPN routing.

list_vpn_policies

Show all VPN routing policies.

get_vpn_server_status

Check VPN server status and connected clients.

get_vpn_server_users

List authorized VPN server users.