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

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:

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

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

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:

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:

For Docker Installation:

Claude Code (NPM Installation)

Config file: ~/.claude/settings.json

For Local Installation:

For Docker Installation:

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:

For Docker Installation:

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

System Information Tools (14)

MAC Filtering Tools (3)

DHCP Management Tools (3)

Internet Access Control Tools (2)

VPN Routing Policy Tools (3)

VPN Server Monitoring Tools (2)

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

Permission Denied

Import Errors

Volume Mount Errors (Docker)

If you see an error like:

Cause: JSON configuration files do not expand shell variables like ${HOME} or ~.

Solution: Replace ${HOME} with your actual home directory path in the configuration:

To find your home directory:

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:

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: Note: Downloads are MD5 checksum verified for integrity

2. Edit the file locally with your text editor:

   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: Note: Uploads are MD5 checksum verified to ensure file integrity

4. Apply changes:

   "Restart the dnsmasq service"

   Uses:

⚠️ 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:

Replace

Managing NVRAM Variables

NVRAM stores persistent router configuration. Warning: Incorrect values can break your router!

Get a Single NVRAM Variable

Uses:

Set an NVRAM Variable (Without Commit)

Uses:

This sets the variable in RAM but won't persist across reboots.

Set and Commit NVRAM Variable

Uses:

⚠️ Warning: Committed changes persist across reboots. Double-check values before committing!

Backup NVRAM to File

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

MD5 checksum automatically verified to ensure script integrity

Then make it executable:

View Existing Scripts

Read a Script's Contents

Monitoring and Diagnostics

Check System Resources

Uses:

List All Connected Devices

Uses:

Find a Specific Device

Check WiFi Status

Uses:

View System Logs

Uses:

Monitor Running Processes

Uses:

VPN Management

Check VPN Status

Uses:

View VPN Configuration

Restart VPN Client

Uses:

Service Management

Restart Wireless Service

Useful after changing WiFi settings

Restart WAN Connection

Forces WAN reconnection

Restart Web Interface

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

Checksum verified for integrity

Upload Configuration Files

Checksum verified to prevent corruption

Check File Permissions

Make Script Executable

Advanced Router Operations

Backup Entire JFFS Partition

View Network Connections

Check Router Temperature (if supported)

Reboot Router

Requires confirmation -

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

Upload Custom Scripts

Monitor Router Health

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

• MCP Documentation

• Paramiko Documentation

License

MIT License - Use at your own risk. Always maintain backups of your router configuration.