kcsoukup/asus-merlin-mcp repository overview

⁠ASUS Merlin MCP Server

Model Context Protocol (MCP) server for managing ASUS routers running Merlin firmware. Enables AI assistants like Claude to interact with your router via secure SSH connections.

⁠🚨 BREAKING CHANGE - v3.x Security Update

Docker containers now run as rootless (non-root user mcpuser) for enhanced security.

If upgrading from v1.0.0 to v3.x, you MUST update your MCP configuration with TWO changes:

Required Changes:

1. Update Volume Mount in Docker args:

   "-v", "~/.ssh:/home/mcpuser/.ssh:ro"  // Changed from /root/.ssh
   

   Copy

2. Update Environment Variable:

   "ROUTER_KEY_FILE": "/home/mcpuser/.ssh/id_rsa"  // Changed from /root/.ssh/id_rsa
   

   Copy

Complete MCP Configuration Example:

{
  "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 Benefits:

• ✅ Follows Docker security best practices (rootless containers)
• ✅ Reduces attack surface by running as non-privileged user
• ✅ Prevents privilege escalation vulnerabilities

⁠Features

This MCP server provides 47 tools across 8 categories for comprehensive router management:

• System Information (14 tools): Router info, device lists, WiFi status, services, NVRAM, file operations, processes
• Firewall Management (2 tools): Configure firewall settings and VPN passthrough
• URL/Keyword Filtering (9 tools): Global URL/keyword content filtering
• Network Service Filtering (6 tools): Block/allow services by IP/port/protocol with scheduling (NEW in v3.0)
• MAC Filtering (3 tools): Add/remove/list WiFi access control rules
• DHCP Management (3 tools): Add/remove/list static IP reservations
• Internet Access Control (2 tools): Block/unblock devices (parental controls)
• VPN Routing Policy (3 tools): Route devices through VPN clients (Asuswrt-Merlin only)
• VPN Server Monitoring (2 tools): Monitor VPN server status and users

For detailed example prompts for each tool, see TOOLS_PROMPTS.md⁠

⁠Quick Start

⁠Pull the Image

docker pull kcsoukup/asus-merlin-mcp:latest

⁠Configure Claude Desktop (or other assistant), SSH Key Recommended!

Config file locations:

• Linux: ~/.config/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "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_PORT=22",
        "-e", "ROUTER_USER=admin",
        "-e", "ROUTER_KEY_FILE=/home/mcpuser/.ssh/id_rsa",
        "kcsoukup/asus-merlin-mcp:latest"
      ]
    }
  }
}

⁠Documentation

Full documentation, configuration examples, and security best practices available at: https://github.com/kcsoukup/asus-merlin-mcp⁠

⁠Requirements

• ASUS router running ASUSWRT Merlin firmware (standard tools work with standard ASUS firmware)
• SSH enabled on router
• SSH key configured (recommended) or password authentication

⁠Security

• This server uses SSH for all router communications. SSH key authentication is strongly recommended over password authentication.
• Container runs rootless.
• All packages updated upon build to address any current vulnerabilities

⁠Support

• GitHub Issues: https://github.com/kcsoukup/asus-merlin-mcp/issues⁠
• SNBForums Discussion: https://www.snbforums.com/forums/asus-wi-fi.37/⁠

⁠Repository Tags

• mcp
• asus
• asuswrt
• merlin
• router
• claude
• ai-tools
• ssh
• network-management
• model-context-protocol

⁠License

See LICENSE file in the repository: https://github.com/kcsoukup/asus-merlin-mcp⁠