ASUS Merlin Router MCP Server

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

---

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
   

2. Update Environment Variable:

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

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

Prerequisites

Router Setup

1. Enable SSH on your router:

   • Login to router web interface
   • Go to Administration > System
   • Set Enable SSH to LAN only (or LAN & WAN if needed)
   • Click Apply

2. (Recommended) Set up SSH key authentication:

   # On your Debian workstation
   ssh-keygen -t rsa -b 4096
   
   # Copy your public key to router
   ssh-copy-id admin@192.168.1.1
   
   # Or manually via web interface:
   # Administration > System > SSH Authentication Key
   

Debian Workstation Setup

# Install Python 3.11+ if not already installed
sudo apt update
sudo apt install python3 python3-pip python3-venv

# Optional: Install Docker for containerized deployment
sudo apt install docker.io docker-compose

Installation

Option 1: Local Installation (Recommended for Development)

1. Clone or create project directory:

   mkdir asus-merlin-mcp
   cd asus-merlin-mcp
   

2. Save the MCP server code as asus_merlin_mcp.py

3. Create virtual environment and install dependencies:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

4. Configure router connection:

   cp .env.example .env
   nano .env  # Edit with your router details
   

5. Test the connection:

   # Export environment variables
   export $(cat .env | xargs)
   
   # Run the server (it will connect via stdio)
   python asus_merlin_mcp.py
   

Option 2: Docker Installation

Quick Start - Pull from Docker Hub:

# Pull the pre-built image (use :latest for current version or specific version tag)
docker pull kcsoukup/asus-merlin-mcp:latest

Available versions: v1.0.0, v3.0, latest

Build from Source (Alternative):

1. Build the Docker image:

   docker build -t asus-merlin-mcp .
   

2. Edit docker-compose.yml with your router credentials

   # Optional -- The credentials are passed to the container via the MCP configurations in Claude or other chatbots.
   

3. Run with Docker Compose:

   docker-compose up -d
   

Claude Configuration

The configuration location depends on which Claude installation you're using:

Claude Code (Native Installation)

MCP servers are automatically configured in ~/.claude.json under your project path:

Config file: ~/.claude.json

For Local Installation:

{
  "installMethod": "native",
  "projects": {
    "/path/to/asus-merlin-mcp": {
      "mcpServers": {
        "asus-router": {
          "command": "/path/to/asus-merlin-mcp/venv/bin/python",
          "args": ["/path/to/asus-merlin-mcp/asus_merlin_mcp.py"],
          "env": {
            "ROUTER_HOST": "192.168.1.1",
            "ROUTER_PORT": "22",
            "ROUTER_USER": "admin",
            "ROUTER_KEY_FILE": "/home/yourusername/.ssh/id_rsa"
          }
        }
      }
    }
  }
}

For Docker Installation:

{
  "installMethod": "native",
  "projects": {
    "/path/to/asus-merlin-mcp": {
      "mcpServers": {
        "asus-router": {
          "com…