Model Context Protocol (MCP) server for managing ASUS routers running Asuswrt-Merlin firmware via SSH/SCP.
- System Information: Get router uptime, memory, CPU, firmware version
- Device Management: List connected devices
- WiFi Control: Check WiFi status across all radios
- Service Management: Restart services (wireless, VPN, etc.)
- NVRAM Operations: Read/write router configuration variables
- File Operations: Upload/download files via SCP
- VPN Management: Check VPN status
- Process Monitoring: List running processes
- Custom Commands: Execute any SSH command
-
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
-
(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
# Install Python 3.11+ if not already installed
sudo apt update
sudo apt install python3 python3-pip python3-venv
# Optional: Install Docker/Podman for containerized deployment
sudo apt install docker.io docker-compose
# OR
sudo apt install podman podman-compose
# OR
pip3 install podman-compose-
Clone or create project directory:
mkdir asus-merlin-mcp cd asus-merlin-mcp -
Save the MCP server code as
asus_merlin_mcp.py -
Create virtual environment and install dependencies:
python3 -m venv venv source venv/bin/activate pip install -r requirements.txt -
Configure router connection:
cp .env.example .env nano .env # Edit with your router details -
Test the connection:
# Export environment variables export $(cat .env | xargs) # Run the server (it will connect via stdio) python asus_merlin_mcp.py
-
Build the Docker image:
docker build -t asus-merlin-mcp . -
Edit docker-compose.yml with your router credentials
-
Run with Docker Compose:
docker-compose up -d
# Build with Podman
podman build -t asus-merlin-mcp .
# Run with Podman Compose
podman-compose up -d
# Or run directly
podman run -it --rm \
-v ~/.ssh:/root/.ssh:ro \
-e ROUTER_HOST=192.168.1.1 \
-e ROUTER_PORT=22 \
-e ROUTER_USER=admin \
-e ROUTER_KEY_FILE=/root/.ssh/id_rsa \
asus-merlin-mcpThe configuration location depends on which Claude installation you're using:
MCP servers are automatically configured in ~/.claude.json under your project path:
Config file: ~/.claude.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"
}
}
}
}
}
}{
"installMethod": "native",
"projects": {
"/path/to/asus-merlin-mcp": {
"mcpServers": {
"asus-router": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/home/yourusername/.ssh:/root/.ssh:ro",
"-e", "ROUTER_HOST=192.168.1.1",
"-e", "ROUTER_PORT=22",
"-e", "ROUTER_USER=admin",
"-e", "ROUTER_KEY_FILE=/root/.ssh/id_rsa",
"asus-merlin-mcp"
]
}
}
}
}
}{
"installMethod": "native",
"projects": {
"/path/to/asus-merlin-mcp": {
"mcpServers": {
"asus-router": {
"command": "podman",
"args": [
"run", "-i", "--rm",
"-v", "/home/yourusername/.ssh:/root/.ssh:ro",
"-e", "ROUTER_HOST=192.168.1.1",
"-e", "ROUTER_PORT=22",
"-e", "ROUTER_USER=admin",
"-e", "ROUTER_KEY_FILE=/root/.ssh/id_rsa",
"asus-merlin-mcp"
]
}
}
}
}
}Config file: ~/.claude/settings.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"
}
}
}
}{
"mcpServers": {
"asus-router": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/home/yourusername/.ssh:/root/.ssh:ro",
"-e", "ROUTER_HOST=192.168.1.1",
"-e", "ROUTER_PORT=22",
"-e", "ROUTER_USER=admin",
"-e", "ROUTER_KEY_FILE=/root/.ssh/id_rsa",
"asus-merlin-mcp"
]
}
}
}{
"mcpServers": {
"asus-router": {
"command": "podman",
"args": [
"run", "-i", "--rm",
"-v", "/home/yourusername/.ssh:/root/.ssh:ro",
"-e", "ROUTER_HOST=192.168.1.1",
"-e", "ROUTER_PORT=22",
"-e", "ROUTER_USER=admin",
"-e", "ROUTER_KEY_FILE=/root/.ssh/id_rsa",
"asus-merlin-mcp"
]
}
}
}Config file locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.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"
}
}
}
}{
"mcpServers": {
"asus-router": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/home/yourusername/.ssh:/root/.ssh:ro",
"-e", "ROUTER_HOST=192.168.1.1",
"-e", "ROUTER_PORT=22",
"-e", "ROUTER_USER=admin",
"-e", "ROUTER_KEY_FILE=/root/.ssh/id_rsa",
"asus-merlin-mcp"
]
}
}
}{
"mcpServers": {
"asus-router": {
"command": "podman",
"args": [
"run", "-i", "--rm",
"-v", "/home/yourusername/.ssh:/root/.ssh:ro",
"-e", "ROUTER_HOST=192.168.1.1",
"-e", "ROUTER_PORT=22",
"-e", "ROUTER_USER=admin",
"-e", "ROUTER_KEY_FILE=/root/.ssh/id_rsa",
"asus-merlin-mcp"
]
}
}
}Important Notes:
- Replace
/home/yourusernamewith 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
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"
| Tool | Description |
|---|---|
get_router_info |
System info (uptime, memory, firmware) |
get_connected_devices |
List DHCP clients |
get_wifi_status |
WiFi status for all radios |
restart_service |
Restart specific service |
reboot_router |
Reboot router (requires confirmation) |
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 (tries SFTP, falls back to shell if unavailable) |
download_file |
Download file (tries SFTP, falls back to shell if unavailable) |
get_vpn_status |
Check VPN status |
list_processes |
Show running processes |
wireless- WiFi serviceswan- WAN connectionhttpd- Web interfacevpnclient1- VPN client 1vpnclient2- VPN client 2dnsmasq- DNS/DHCP server
- Use SSH keys instead of passwords for better security
- Enable SSH on LAN only unless you need WAN access
- Be careful with NVRAM operations - incorrect values can break your router
- Test commands manually first before automating
- Keep backups of your router configuration
# Test SSH connection manually
ssh admin@192.168.1.1
# Check if SSH is enabled on router
# Via web interface: Administration > System > Enable SSH# 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"# Ensure virtual environment is activated
source venv/bin/activate
# Reinstall dependencies
pip install -r requirements.txt --force-reinstallIf 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:
// Wrong - will not work:
"-v", "${HOME}/.ssh:/root/.ssh:ro"
// Correct - use absolute path:
"-v", "/home/triskull/.ssh:/root/.ssh:ro"To find your home directory:
echo $HOME
# Output: /home/triskullThis section provides practical examples for common router administration tasks using the MCP tools.
The router's custom hosts file (/jffs/configs/hosts.add) allows you to add static DNS entries that persist across reboots.
Via Claude:
"Show me the contents of /jffs/configs/hosts.add"
MCP Tool Used: read_file
Option 1: Download, Edit, Upload (Recommended)
-
Download the file:
"Download /jffs/configs/hosts.add from the router to ./hosts.add"Uses:
download_filetool Note: Downloads are MD5 checksum verified for integrity -
Edit the file locally with your text editor:
nano hosts.add # Add line like: # 192.168.0.100 newserver.damage.inc newserver
-
Upload back to router:
"Upload ./hosts.add to /jffs/configs/hosts.add on the router"Uses:
upload_filetool Note: Uploads are MD5 checksum verified to ensure file integrity -
Apply changes:
"Restart the dnsmasq service"Uses:
restart_servicewithservice_name: dnsmasq
Option 2: Direct Command
Via Claude:
"Execute this command on the router: echo '192.168.0.100 newserver.damage.inc newserver' >> /jffs/configs/hosts.add"
Uses: execute_command tool
Then restart dnsmasq:
"Restart the dnsmasq service"
- Download the hosts file
- Edit locally to change the desired line
- Upload back to router
- Restart dnsmasq
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
NVRAM stores persistent router configuration. Warning: Incorrect values can break your router!
"Get the NVRAM variable wan_ipaddr"
Uses: get_nvram_variable
"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 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!
"Execute this command: nvram show > /jffs/nvram_backup_$(date +%Y%m%d).txt"
"Download /jffs/nvram_backup_20250101.txt to ./nvram_backup.txt"
Scripts in /jffs/scripts/ persist across reboots and can run at various router events.
init-start- First script run during bootservices-start- Runs after router services startwan-start- Runs when WAN interface comes upfirewall-start- Runs when firewall starts
"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"
"Execute this command: ls -la /jffs/scripts/"
"Read the file /jffs/scripts/firewall-start"
"What's my router's current status?"
Uses: get_router_info - Shows uptime, memory, firmware
"List all connected devices on my network"
Uses: get_connected_devices - Shows DHCP leases
"Show connected devices and look for hostname 'rpiserver'"
"Execute this command: cat /var/lib/misc/dnsmasq.leases | grep rpiserver"
"What's my WiFi status?"
Uses: get_wifi_status - Shows radio status and SSIDs
"Read the file /jffs/syslog.log with max 50 lines"
Uses: read_file with max_lines: 50
"List all running processes"
"List processes filtered by 'vpn'"
Uses: list_processes with optional filter
"What's my VPN status?"
Uses: get_vpn_status - Shows client/server states
"Execute this command: nvram show | grep vpn_client1"
"Restart the vpnclient1 service"
Uses: restart_service with service_name: vpnclient1
"Restart the wireless service"
Useful after changing WiFi settings
"Restart the wan service"
Forces WAN reconnection
"Restart the httpd service"
Restarts the router's web UI
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 /jffs/configs/dnsmasq.conf.add to ./dnsmasq.conf.add"
Checksum verified for integrity
"Upload ./firewall-rules.txt to /jffs/scripts/firewall-start"
Checksum verified to prevent corruption
"Execute this command: ls -la /jffs/scripts/"
"Execute this command: chmod +x /jffs/scripts/script-name"
"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"
"Execute this command: netstat -an | grep ESTABLISHED"
"Execute this command: wl -i eth1 phy_tempsense"
"Reboot the router"
Requires confirmation - ⚠️ This will disconnect all clients!
- Always test commands manually first before automating them
- Keep backups of configuration files before making changes
- Use descriptive hostnames in hosts.add for easier management
- Document your custom scripts with comments
- Restart services after configuration changes to apply them
- Use SSH keys instead of passwords for better security
- Be cautious with NVRAM commits - test without commit first
- Monitor logs after making changes to catch issues early
# Via Claude: "Download the router's NVRAM backup"
# This will use the download_file tool to get /jffs/nvram/nvram.txt# Upload a script to run on router boot
# Files in /jffs/scripts/ persist across reboots# Set up periodic checks via cron jobs on the router
# Use the execute_command tool to create cron entriesFeel free to extend this MCP server with additional tools for:
- Traffic monitoring
- Firewall rule management
- Bandwidth statistics
- Port forwarding configuration
- Guest network management
MIT License - Use at your own risk. Always maintain backups of your router configuration.