ASUS Merlin Router MCP Server

# 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:** | Component | v1.0.0 (Deprecated) | v3.x (Current) | |-----------|---------------------|----------------| | Container User | `root` | `mcpuser` (UID 1000) | | Volume Mount | `~/.ssh:/root/.ssh:ro` | `~/.ssh:/home/mcpuser/.ssh:ro` | | SSH Key Path | `/root/.ssh/id_rsa` | `/home/mcpuser/.ssh/id_rsa` | **Required Changes:** 1. **Update Volume Mount** in Docker args: ```json "-v", "~/.ssh:/home/mcpuser/.ssh:ro" // Changed from /root/.ssh ``` 2. **Update Environment Variable**: ```json "ROUTER_KEY_FILE": "/home/mcpuser/.ssh/id_rsa" // Changed from /root/.ssh/id_rsa ``` **Complete MCP Configuration Example:** ```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_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](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: ```bash # 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 ```bash # 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:** ```bash 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:** ```bash python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` 4. **Configure router connection:** ```bash cp .env.example .env nano .env # Edit with your router details ``` 5. **Test the connection:** ```bash # 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: ```bash # 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:** ```bash docker build -t asus-merlin-mcp . ``` 2. **Edit docker-compose.yml with your router credentials** ```bash # Optional -- The credentials are passed to the container via the MCP configurations in Claude or other chatbots. ``` 3. **Run with Docker Compose:** ```bash 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: ```json { "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: ```json { "installMethod": "native", "projects": { "/path/to/asus-merlin-mcp": { "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" ] } } } } } ``` --- ### Claude Code (NPM Installation) **Config file:** `~/.claude/settings.json` #### For Local Installation: ```json { "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: ```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" ] } } } ``` --- ### Claude Desktop **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` #### For Local Installation: ```json { "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: ```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" ] } } } ``` **Important Notes:** - Replace `/home/yourusername` with your actual home directory path (e.g., `/home/triskull`) - Do NOT use `${HOME}` or `~` in JSON configuration files - they will not expand - After updating the configuration file, restart Claude Code or Claude Desktop for the changes to take effect ## Usage Examples Once configured in Claude Desktop, you can interact with your router: **Example prompts:** - "What's the current status of my router?" - "List all connected devices" - "Restart the wireless service" - "Show me the WiFi configuration" - "Get the value of wan_ipaddr from NVRAM" - "Upload this backup script to /jffs/scripts/" - "Check if VPN is running" - "Show me the router's system log" ## Available Tools For detailed example prompts, see **[TOOLS_PROMPTS.md](TOOLS_PROMPTS.md)** ### System Information Tools (14) | Tool | Description | |------|-------------| | `get_router_info` | System info (uptime, memory, firmware) | | `get_connected_devices` | List DHCP clients | | `get_all_network_devices` | Comprehensive device list (DHCP + static + ARP) | | `get_wifi_status` | WiFi status for all radios | | `restart_service` | Restart specific service | | `reboot_router` | Reboot router (requires confirmation) | | `get_vpn_status` | Check VPN client/server status | | `list_processes` | Show running processes | | `get_nvram_variable` | Read NVRAM variable | | `set_nvram_variable` | Write NVRAM variable | | `execute_command` | Run custom SSH command | | `read_file` | Read file from router | | `upload_file` | Upload file (MD5 verified) | | `download_file` | Download file (MD5 verified) | ### MAC Filtering Tools (3) | Tool | Description | |------|-------------| | `add_mac_filter` | Add device to MAC filter (whitelist/blacklist) | | `remove_mac_filter` | Remove device from MAC filter | | `list_mac_filters` | Show current MAC filters | ### DHCP Management Tools (3) | Tool | Description | |------|-------------| | `add_dhcp_reservation` | Reserve IP for MAC address (static lease) | | `remove_dhcp_reservation` | Remove DHCP reservation | | `list_dhcp_reservations` | Show all DHCP reservations | ### Internet Access Control Tools (2) | Tool | Description | |------|-------------| | `block_device_internet` | Block/unblock device internet (parental controls) | | `list_blocked_devices` | Show blocked devices | ### VPN Routing Policy Tools (3) | Tool | Description | |------|-------------| | `add_vpn_routing_policy` | Route device through VPN client | | `remove_vpn_routing_policy` | Remove device from VPN routing | | `list_vpn_policies` | Show all VPN routing policies | ### VPN Server Monitoring Tools (2) | Tool | Description | |------|-------------| | `get_vpn_server_status` | VPN server status and connected clients | | `get_vpn_server_users` | List authorized VPN server users | ## Common Services to Restart - `wireless` - WiFi services - `wan` - WAN connection - `httpd` - Web interface - `vpnclient1` - VPN client 1 - `vpnclient2` - VPN client 2 - `dnsmasq` - DNS/DHCP server ## Security Notes 1. **Use SSH keys instead of passwords** for better security 2. **Enable SSH on LAN only** unless you need WAN access 3. **Be careful with NVRAM operations** - incorrect values can break your router 4. **Test commands manually first** before automating 5. **Keep backups** of your router configuration ## Troubleshooting ### Connection Issues ```bash # Test SSH connection manually ssh admin@192.168.1.1 # Check if SSH is enabled on router # Via web interface: Administration > System > Enable SSH ``` ### Permission Denied ```bash # Ensure SSH keys are readable chmod 600 ~/.ssh/id_rsa chmod 644 ~/.ssh/id_rsa.pub # Verify key is added to router ssh admin@192.168.1.1 "cat /tmp/home/root/.ssh/authorized_keys" ``` ### Import Errors ```bash # Ensure virtual environment is activated source venv/bin/activate # Reinstall dependencies pip install -r requirements.txt --force-reinstall ``` ### Volume Mount Errors (Docker) If you see an error like: ``` Error: error creating named volume "${HOME}/.keys": error running volume create option: names must match [a-zA-Z0-9][a-zA-Z0-9_.-]*: invalid argument ``` **Cause:** JSON configuration files do not expand shell variables like `${HOME}` or `~`. **Solution:** Replace `${HOME}` with your actual home directory path in the configuration: ```json // Wrong - will not work: "-v", "${HOME}/.ssh:/home/mcpuser/.ssh:ro" // Correct - use absolute path: "-v", "/home/triskull/.ssh:/home/mcpuser/.ssh:ro" ``` To find your home directory: ```bash echo $HOME # Output: /home/triskull ``` ## How-To Guide: Common Administrative Tasks This section provides practical examples for common router administration tasks using the MCP tools. ### Managing the Hosts File The router's custom hosts file (`/jffs/configs/hosts.add`) allows you to add static DNS entries that persist across reboots. #### View Current Hosts File **Via Claude:** ``` "Show me the contents of /jffs/configs/hosts.add" ``` **MCP Tool Used:** `read_file` #### Add a New Host Entry **Option 1: Download, Edit, Upload (Recommended)** 1. Download the file: ``` "Download /jffs/configs/hosts.add from the router to ./hosts.add" ``` *Uses: `download_file` tool* *Note: Downloads are MD5 checksum verified for integrity* 2. Edit the file locally with your text editor: ```bash nano hosts.add # Add line like: # 192.168.0.100 newserver.damage.inc newserver ``` 3. Upload back to router: ``` "Upload ./hosts.add to /jffs/configs/hosts.add on the router" ``` *Uses: `upload_file` tool* *Note: Uploads are MD5 checksum verified to ensure file integrity* 4. Apply changes: ``` "Restart the dnsmasq service" ``` *Uses: `restart_service` with `service_name: dnsmasq`* **⚠️ WARNING:** Do NOT use `execute_command` with echo/heredoc for file operations. Always use the download → edit → upload workflow shown above for file safety and MD5 verification. #### Update an Existing Host Entry 1. Download the hosts file 2. Edit locally to change the desired line 3. Upload back to router 4. Restart dnsmasq #### Remove a Host Entry Via Claude: ``` "Execute this command: sed -i '/hostname-to-remove/d' /jffs/configs/hosts.add" "Restart the dnsmasq service" ``` *Replace `hostname-to-remove` with the actual hostname or IP* ### Managing NVRAM Variables NVRAM stores persistent router configuration. **Warning:** Incorrect values can break your router! #### Get a Single NVRAM Variable ``` "Get the NVRAM variable wan_ipaddr" ``` *Uses: `get_nvram_variable`* #### Set an NVRAM Variable (Without Commit) ``` "Set NVRAM variable custom_setting to value123 but don't commit" ``` *Uses: `set_nvram_variable` with `commit: false`* This sets the variable in RAM but won't persist across reboots. #### Set and Commit NVRAM Variable ``` "Set NVRAM variable custom_setting to value123 and commit it" ``` *Uses: `set_nvram_variable` with `commit: true`* **⚠️ Warning:** Committed changes persist across reboots. Double-check values before committing! #### Backup NVRAM to File ``` "Execute this command: nvram show > /jffs/nvram_backup_$(date +%Y%m%d).txt" "Download /jffs/nvram_backup_20250101.txt to ./nvram_backup.txt" ``` ### Managing Custom Scripts Scripts in `/jffs/scripts/` persist across reboots and can run at various router events. #### Common Script Hooks - `init-start` - First script run during boot - `services-start` - Runs after router services start - `wan-start` - Runs when WAN interface comes up - `firewall-start` - Runs when firewall starts #### Upload a Custom Script ``` "Upload ./my-custom-script.sh to /jffs/scripts/services-start on the router" ``` *MD5 checksum automatically verified to ensure script integrity* Then make it executable: ``` "Execute this command: chmod +x /jffs/scripts/services-start" ``` #### View Existing Scripts ``` "Execute this command: ls -la /jffs/scripts/" ``` #### Read a Script's Contents ``` "Read the file /jffs/scripts/firewall-start" ``` ### Monitoring and Diagnostics #### Check System Resources ``` "What's my router's current status?" ``` *Uses: `get_router_info` - Shows uptime, memory, firmware* #### List All Connected Devices ``` "List all connected devices on my network" ``` *Uses: `get_connected_devices` - Shows DHCP leases* #### Find a Specific Device ``` "Show connected devices and look for hostname 'rpiserver'" "Execute this command: cat /var/lib/misc/dnsmasq.leases | grep rpiserver" ``` #### Check WiFi Status ``` "What's my WiFi status?" ``` *Uses: `get_wifi_status` - Shows radio status and SSIDs* #### View System Logs ``` "Read the file /jffs/syslog.log with max 50 lines" ``` *Uses: `read_file` with `max_lines: 50`* #### Monitor Running Processes ``` "List all running processes" "List processes filtered by 'vpn'" ``` *Uses: `list_processes` with optional filter* ### VPN Management #### Check VPN Status ``` "What's my VPN status?" ``` *Uses: `get_vpn_status` - Shows client/server states* #### View VPN Configuration ``` "Execute this command: nvram show | grep vpn_client1" ``` #### Restart VPN Client ``` "Restart the vpnclient1 service" ``` *Uses: `restart_service` with `service_name: vpnclient1`* ### Service Management #### Restart Wireless Service ``` "Restart the wireless service" ``` *Useful after changing WiFi settings* #### Restart WAN Connection ``` "Restart the wan service" ``` *Forces WAN reconnection* #### Restart Web Interface ``` "Restart the httpd service" ``` *Restarts the router's web UI* ### File Management **Note:** All file uploads and downloads are cryptographically verified using MD5 checksums to ensure data integrity. This is especially important for binary files, scripts, and executables. #### Download Router Files ``` "Download /jffs/configs/dnsmasq.conf.add to ./dnsmasq.conf.add" ``` *Checksum verified for integrity* #### Upload Configuration Files ``` "Upload ./firewall-rules.txt to /jffs/scripts/firewall-start" ``` *Checksum verified to prevent corruption* #### Check File Permissions ``` "Execute this command: ls -la /jffs/scripts/" ``` #### Make Script Executable ``` "Execute this command: chmod +x /jffs/scripts/script-name" ``` ### Advanced Router Operations #### Backup Entire JFFS Partition ``` "Execute this command: tar -czf /tmp/jffs_backup_$(date +%Y%m%d).tar.gz /jffs/" "Download /tmp/jffs_backup_20250101.tar.gz to ./router_backup.tar.gz" ``` #### View Network Connections ``` "Execute this command: netstat -an | grep ESTABLISHED" ``` #### Check Router Temperature (if supported) ``` "Execute this command: wl -i eth1 phy_tempsense" ``` #### Reboot Router ``` "Reboot the router" ``` *Requires confirmation - **⚠️ This will disconnect all clients!*** ### Tips and Best Practices 1. **Always test commands manually first** before automating them 2. **Keep backups** of configuration files before making changes 3. **Use descriptive hostnames** in hosts.add for easier management 4. **Document your custom scripts** with comments 5. **Restart services after configuration changes** to apply them 6. **Use SSH keys** instead of passwords for better security 7. **Be cautious with NVRAM commits** - test without commit first 8. **Monitor logs** after making changes to catch issues early ## Advanced Usage ### Backup Router Configuration ```bash # Via Claude: "Download the router's NVRAM backup" # This will use the download_file tool to get /jffs/nvram/nvram.txt ``` ### Upload Custom Scripts ```bash # Upload a script to run on router boot # Files in /jffs/scripts/ persist across reboots ``` ### Monitor Router Health ```bash # Set up periodic checks via cron jobs on the router # Use the execute_command tool to create cron entries ``` ## Contributing Feel free to extend this MCP server with additional tools for: - Traffic monitoring - Firewall rule management - Bandwidth statistics - Port forwarding configuration - Guest network management ## Resources - [Asuswrt-Merlin Wiki](https://github.com/RMerl/asuswrt-merlin.ng/wiki) - [MCP Documentation](https://modelcontextprotocol.io/) - [Paramiko Documentation](https://www.paramiko.org/) ## License MIT License - Use at your own risk. Always maintain backups of your router configuration.