ASUS Merlin Router MCP Server

华硕Merlin路由器MCP服务器

模型上下文协议（MCP）服务器，用于通过SSH/SCP管理运行华硕Merlin固件的华硕路由器。

______________________________________________________________________

🚨 重大变更-v3.x安全更新

Docker容器现在以无根（非root用户）运行 mcpuser)以增强安全性。

如果从v1.0.0升级到v3.x，您必须用两个更改来更新MCP配置：

所需更改：

1. 更新卷装载 在Docker参数中：

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

1. 更新环境变量:

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

完整的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_USER=admin",
        "-e", "ROUTER_KEY_FILE=/home/mcpuser/.ssh/id_rsa",
        "kcsoukup/asus-merlin-mcp:latest"
      ]
    }
  }
}

安全优势：

• ✅ 遵循Docker安全最佳实践（无根容器）
• ✅ 通过以非特权用户身份运行来减少攻击面
• ✅ 防止特权升级漏洞

______________________________________________________________________

特性

此MCP服务器提供 47工具 涵盖8个类别，用于全面的路由器管理：

• 系统信息 （14个工具）：路由器信息、设备列表、WiFi状态、服务、NVRAM、文件操作、进程
• 防火墙管理 （2个工具）：配置防火墙设置和VPN直通
• URL/关键字筛选 （9个工具）：全局URL/关键字内容过滤
• 网络服务过滤 （6个工具）：通过带有调度的IP/端口/协议阻止/允许服务（v3.0中的新功能）
• MAC地址过滤 （3个工具）：添加/删除/列出WiFi访问控制规则
• DHCP管理 （3个工具）：添加/删除/列出静态IP保留
• 互联网访问控制 （2个工具）：阻止/取消阻止设备（家长控制）
• VPN路由策略 （3个工具）：通过VPN客户端路由设备（仅限华硕Merlin）
• VPN服务器监控 （2个工具）：监控VPN服务器状态和用户

有关每个工具的详细示例提示，请参见 工具\_ PROMPTS.md

先决条件

路由器设置

1. 在路由器上启用SSH：

- 登录路由器web界面 - 首选 管理>系统 - 集 启用SSH 到 仅限局域网 （或局域网和广域网，如果需要） - 点击 应用

1. （推荐）设置SSH密钥身份验证：

   # 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工作站设置

# 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

安装

选项1：本地安装（建议用于开发）

1. 克隆或创建项目目录：

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

1. 将MCP服务器代码另存为 asus_merlin_mcp.py

1. 创建虚拟环境并安装依赖关系：

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

1. 配置路由器连接：

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

1. 测试连接：

   # Export environment variables
   export $(cat .env | xargs)

   # Run the server (it will connect via stdio)
   python asus_merlin_mcp.py

选项2：Docker安装

快速入门-从Docker Hub拉取：

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

可用版本： v1.0.0, v3.0, latest

从源代码构建（替代）：

1. 构建Docker镜像：

   docker build -t asus-merlin-mcp .

1. 使用您的路由器凭据编辑docker-compose.yml

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

1. 使用Docker Compose运行：

   docker-compose up -d

克劳德配置

配置位置取决于您使用的Claude安装：

Claude代码（本地安装）

MCP服务器在中自动配置 ~/.claude.json 在您的项目路径下：

配置文件： ~/.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"
          }
        }
      }
    }
  }
}

对于Docker安装：

{
  "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"
          ]
        }
      }
    }
  }
}

______________________________________________________________________

克劳德代码（NPM安装）

配置文件： ~/.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"
      }
    }
  }
}

对于Docker安装：

{
  "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"
      ]
    }
  }
}

______________________________________________________________________

克劳德桌面

配置文件位置：

• Linux： ~/.config/Claude/claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\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"
      }
    }
  }
}

对于Docker安装：

{
  "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"
      ]
    }
  }
}

重要提示：

• 替换 /home/yourusername 使用您的实际主目录路径（例如。， /home/triskull)
• 别用 ${HOME} 或 ~ 在JSON配置文件中-它们不会展开
• 更新配置文件后，重新启动Claude Code或Claude Desktop以使更改生效

用法示例

在Claude Desktop中配置后，您可以与路由器进行交互：

示例提示：

• “我的路由器的当前状态如何？”
• “列出所有连接的设备”
• “重新启动无线服务”
• “显示WiFi配置”
• “从NVRAM获取wan_ipadder的值”
• “将此备份脚本上载到/jffs/scripts/”
• “检查VPN是否正在运行”
• “显示路由器的系统日志”

可用工具

有关详细的示例提示，请参见 工具\_ PROMPTS.md

系统信息工具（14）

MAC过滤工具（3）

DHCP管理工具（3）

互联网访问控制工具（2）

VPN路由策略工具（3）

VPN服务器监控工具（2）

要重新启动的公共服务

• wireless -WiFi服务
• wan -广域网连接
• httpd -Web界面
• vpnclient1 -VPN客户端1
• vpnclient2 -VPN客户端2
• dnsmasq -DNS/DHCP服务器

安全说明

1. 使用SSH密钥而不是密码 为了更好的安全性
2. 仅在局域网上启用SSH 除非你需要广域网接入
3. 小心NVRAM操作 -不正确的值可能会损坏路由器
4. 首先手动测试命令 自动化之前
5. 保留备份 您的路由器配置

故障排除

连接问题

# 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-reinstall

卷装载错误（Docker）

如果您看到以下错误：

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

原因： JSON配置文件不扩展shell变量，如 ${HOME} 或 ~.

解决方案： 替换 ${HOME} 在配置中使用您的实际主目录路径：

// Wrong - will not work:
"-v", "${HOME}/.ssh:/home/mcpuser/.ssh:ro"

// Correct - use absolute path:
"-v", "/home/triskull/.ssh:/home/mcpuser/.ssh:ro"

要查找您的主目录，请执行以下操作：

echo $HOME
# Output: /home/triskull

如何指导：常见管理任务

本节提供了使用MCP工具执行常见路由器管理任务的实例。

管理主机文件

路由器的自定义主机文件(/jffs/configs/hosts.add)允许您添加在重新启动后仍然存在的静态DNS条目。

查看当前主机文件

通过克劳德：

"Show me the contents of /jffs/configs/hosts.add"

使用的MCP工具： read_file

添加新主机条目

选项1：下载、编辑、上传（推荐）

1. 下载文件：

   "Download /jffs/configs/hosts.add from the router to ./hosts.add"

*使用： download_file 工具* *注意：下载经过MD5校验和完整性验证*

1. 使用文本编辑器在本地编辑文件：

   nano hosts.add
   # Add line like:
   # 192.168.0.100    newserver.damage.inc    newserver

1. 上传回路由器：

   "Upload ./hosts.add to /jffs/configs/hosts.add on the router"

*使用： upload_file 工具* *注意：上传经过MD5校验和验证，以确保文件完整性*

1. 应用更改：

   "Restart the dnsmasq service"

*使用： restart_service 随着 service_name: dnsmasq*

⚠️ 警告： 别用 execute_command 使用echo/heredoc进行文件操作。始终使用下载→ edit → 上传工作流程如上所示，用于文件安全和MD5验证。

更新现有主机条目

1. 下载hosts文件
2. 在本地编辑以更改所需的行
3. 上传回路由器
4. 重新启动dnsmasq

删除主机条目

通过克劳德：

"Execute this command: sed -i '/hostname-to-remove/d' /jffs/configs/hosts.add"
"Restart the dnsmasq service"

*替换 hostname-to-remove 使用实际主机名或IP*

管理NVRAM变量

NVRAM存储持久路由器配置。 警告： 不正确的值可能会损坏您的路由器！

获取单个NVRAM变量

"Get the NVRAM variable wan_ipaddr"

*使用： get_nvram_variable*

设置NVRAM变量（无提交）

"Set NVRAM variable custom_setting to value123 but don't commit"

*使用： set_nvram_variable 随着 commit: false*

这将在RAM中设置变量，但不会在重新启动后持续存在。

设置并提交NVRAM变量

"Set NVRAM variable custom_setting to value123 and commit it"

*使用： set_nvram_variable 随着 commit: true*

⚠️ 警告： 已提交的更改在重新启动后仍然存在。提交前仔细检查值！

将NVRAM备份到文件

"Execute this command: nvram show > /jffs/nvram_backup_$(date +%Y%m%d).txt"
"Download /jffs/nvram_backup_20250101.txt to ./nvram_backup.txt"

管理自定义脚本

脚本在 /jffs/scripts/ 在重新启动时保持不变，可以在各种路由器事件中运行。

常见脚本挂钩

• init-start -启动期间首次运行脚本
• services-start -路由器服务启动后运行
• wan-start -当WAN接口启动时运行
• firewall-start -防火墙启动时运行

上传自定义脚本

"Upload ./my-custom-script.sh to /jffs/scripts/services-start on the router"

*MD5校验和自动验证，以确保脚本完整性*

然后使其可执行：

"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?"

*使用： get_router_info -显示正常运行时间、内存、固件*

列出所有连接的设备

"List all connected devices on my network"

*使用： get_connected_devices -显示DHCP租约*

查找特定设备

"Show connected devices and look for hostname 'rpiserver'"
"Execute this command: cat /var/lib/misc/dnsmasq.leases | grep rpiserver"

检查WiFi状态

"What's my WiFi status?"

*使用： get_wifi_status -显示收音机状态和SSID*

查看系统日志

"Read the file /jffs/syslog.log with max 50 lines"

*使用： read_file 随着 max_lines: 50*

监控正在运行的进程

"List all running processes"
"List processes filtered by 'vpn'"

*使用： list_processes 带可选过滤器*

VPN管理

检查VPN状态

"What's my VPN status?"

*使用： get_vpn_status -显示客户端/服务器状态*

查看VPN配置

"Execute this command: nvram show | grep vpn_client1"

重新启动VPN客户端

"Restart the vpnclient1 service"

*使用： restart_service 随着 service_name: vpnclient1*

服务管理

重新启动无线服务

"Restart the wireless service"

*更改WiFi设置后有用*

重新启动WAN连接

"Restart the wan service"

*强制广域网重新连接*

重新启动Web界面

"Restart the httpd service"

*重新启动路由器的web UI*

文件管理

注： 所有文件上传和下载都使用MD5校验和进行加密验证，以确保数据完整性。这对于二进制文件、脚本和可执行文件尤其重要。

下载路由器文件

"Download /jffs/configs/dnsmasq.conf.add to ./dnsmasq.conf.add"

*校验和已验证其完整性*

上传配置文件

"Upload ./firewall-rules.txt to /jffs/scripts/firewall-start"

*校验和已验证，以防止腐败*

检查文件权限

"Execute this command: ls -la /jffs/scripts/"

使脚本可执行

"Execute this command: chmod +x /jffs/scripts/script-name"

高级路由器操作

备份整个JFFS分区

"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"

*需要确认- ⚠️ 这将断开所有客户端的连接！*

提示和最佳实践

1. 始终先手动测试命令 在实现自动化之前
2. 保留备份 在进行更改之前，请先查看配置文件
3. 使用描述性主机名 在hosts.add中，便于管理
4. 记录您的自定义脚本 附有评论
5. 配置更改后重新启动服务 应用它们
6. 使用SSH密钥 代替密码以提高安全性
7. 注意NVRAM提交 -不先提交的测试
8. 监控日志 在做出更改以尽早发现问题后

高级用法

备份路由器配置

# 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 entries

贡献

请随时使用以下附加工具扩展此MCP服务器：

• 交通监控
• 防火墙规则管理
• 带宽统计
• 端口转发配置
• 访客网络管理

资源

• 华硕梅林维基
• MCP文件
• Paramiko文档

许可证

MIT许可证-使用风险自负。始终维护路由器配置的备份。