星战科技xingzhan.cloud
返回市场
华硕梅林MCP

华硕梅林MCP

作者：kcsoukup3 星标更新：2025-11-13
安装使用来源：spider==github.com

项目介绍

技术文档摘要

ASUS Merlin 路由器 MCP 服务器

用于通过 SSH/SCP 管理运行 Asuswrt-Merlin 固件的 ASUS 路由器的 Model Context Protocol (MCP) 服务器。

Docker 拉取次数 Docker 镜像版本 Docker 镜像大小

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

Docker 容器现在以非特权用户（mcpuser）运行，以增强安全性。

从 v1.0.0 升级到 v3.x 时，您必须在 MCP 配置中进行两项更改：

组件v1.0.0（已弃用）v3.x（当前）
容器用户rootmcpuser（UID 1000）
卷挂载~/.ssh:/root/.ssh:ro~/.ssh:/home/mcpuser/.ssh:ro
SSH 密钥路径/root/.ssh/id_rsa/home/mcpuser/.ssh/id_rsa

所需更改：

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

    "-v", "~/.ssh:/home/mcpuser/.ssh:ro"  // 更改自 /root/.ssh

  2. 更新环境变量：

    "ROUTER_KEY_FILE": "/home/mcpuser/.ssh/id_rsa"  // 更改自 /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 服务器提供了 8 类别中的 47 个工具，用于全面管理路由器：

  • 系统信息（14 个工具）：路由器信息、设备列表、WiFi 状态、服务、NVRAM、文件操作、进程
  • 防火墙管理（2 个工具）：配置防火墙设置和 VPN 透传
  • URL/关键词过滤（9 个工具）：全局 URL/关键词内容过滤
  • 网络服务过滤（6 个工具）：按 IP/端口/协议阻断/允许服务，并安排时间（v3.0 新增）
  • MAC 过滤（3 个工具）：添加/移除/列出 WiFi 访问控制规则
  • DHCP 管理（3 个工具）：添加/移除/列出静态 IP 预留
  • 互联网访问控制（2 个工具）：阻止/解除设备访问（家长控制）
  • VPN 路由策略（3 个工具）：路由设备通过 VPN 客户端（仅限 Asuswrt-Merlin）
  • VPN 服务器监控（2 个工具）：监控 VPN 服务器状态和用户

对于每个工具的详细示例提示，请参阅 TOOLS_PROMPTS.md

前提条件

路由器设置

  1. 启用路由器上的 SSH：

    • 登录到路由器的 Web 界面
    • 转到 管理 > 系统
    • 将 启用 SSH 设置为 仅 LAN（或 LAN 和 WAN，如果需要）
    • 点击 应用

  2. （推荐）设置 SSH 密钥认证：

    # 在您的 Debian 工作站上
ssh-keygen -t rsa -b 4096

# 将您的公钥复制到路由器
ssh-copy-id admin@192.168.1.1

# 或者通过 Web 界面手动添加：
# 管理 > 系统 > SSH 认证密钥

Debian 工作站设置

# 如果尚未安装，请安装 Python 3.11+
sudo apt update
sudo apt install python3 python3-pip python3-venv

# 可选：安装 Docker 以进行容器化部署
sudo apt install docker.io docker-compose

安装

方案 1：本地安装（推荐用于开发）

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

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

  2. 保存 MCP 服务器代码为 asus_merlin_mcp.py

  3. 创建虚拟环境并安装依赖项：

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

  4. 配置路由器连接：

    cp .env.example .env
nano .env  # 使用您的路由器详细信息编辑

  5. 测试连接：

    # 导出环境变量
export $(cat .env | xargs)

# 运行服务器（它将通过标准 I/O 连接）
python asus_merlin_mcp.py

方案 2：Docker 安装

快速开始 - 从 Docker Hub 拉取：

# 拉取预构建的镜像（使用 :latest 获取最新版本或特定版本标签）
docker pull kcsoukup/asus-merlin-mcp:latest

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

从源构建（替代方案）：

  1. 构建 Docker 镜像：

    docker build -t asus-merlin-mcp .

  2. 编辑 docker-compose.yml 文件，填写您的路由器凭据

    # 可选 -- 凭据通过 Claude 或其他聊天机器人中的 MCP 配置传递给容器。

  3. 使用 Docker Compose 运行：

    docker-compose up -d

Claude 配置

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

Claude Code（原生安装）

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

Claude Code（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"
      ]
    }
  }
}

Claude Desktop

配置文件位置：

  • Linux： ~/.config/Claude/claude_desktop_config.json
  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows： %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）
  • 不要在 JSON 配置文件中使用 ${HOME} 或 ~，它们不会展开
  • 更新配置文件后，请重启 Claude Code 或 Claude Desktop 使更改生效

使用示例

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

示例提示：

  • "我的路由器当前状态是什么？"
  • "列出所有连接的设备"
  • "重启无线服务"
  • "显示 WiFi 配置"
  • "从 NVRAM 获取 wan_ipaddr 的值"
  • "将这个备份脚本上传到 /jffs/scripts/"
  • "检查 VPN 是否正在运行"
  • "显示路由器的系统日志"

可用工具

对于每个工具的详细示例提示，请参阅 TOOLS_PROMPTS.md

系统信息工具（14 个）

工具描述
get_router_info系统信息（运行时间、内存、固件）
get_connected_devices列出 DHCP 客户端
get_all_network_devices全面的设备列表（DHCP + 静态 + ARP）
get_wifi_status所有无线电的 WiFi 状态
restart_service重启特定服务
reboot_router重启路由器（需要确认）
get_vpn_status检查 VPN 客户端/服务器状态
list_processes显示正在运行的进程
get_nvram_variable读取 NVRAM 变量
set_nvram_variable写入 NVRAM 变量
execute_command运行自定义 SSH 命令
read_file从路由器读取文件
upload_file上传文件（MD5 校验）
download_file下载文件（MD5 校验）

MAC 过滤工具（3 个）

工具描述
add_mac_filter将设备添加到 MAC 过滤器（白名单/黑名单）
remove_mac_filter从 MAC 过滤器中移除设备
list_mac_filters显示当前的 MAC 过滤器

DHCP 管理工具（3 个）

工具描述
add_dhcp_reservation为 MAC 地址保留 IP（静态租约）
remove_dhcp_reservation移除 DHCP 预留
list_dhcp_reservations显示所有 DHCP 预留

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

工具描述
block_device_internet阻止/解除设备的互联网访问（家长控制）
list_blocked_devices显示被阻止的设备

VPN 路由策略工具（3 个）

工具描述
add_vpn_routing_policy将设备路由到 VPN 客户端
remove_vpn_routing_policy从 VPN 路由中移除设备
list_vpn_policies显示所有 VPN 路由策略

VPN 服务器监控工具（2 个）

工具描述
get_vpn_server_status显示 VPN 服务器状态和连接的客户端
get_vpn_server_users列出授权的 VPN 服务器用户

常见服务重启

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

安全注意事项

  1. 使用 SSH 密钥而不是密码 以提高安全性
  2. 仅在 LAN 上启用 SSH，除非需要 WAN 访问
  3. 小心操作 NVRAM - 错误的值可能会破坏您的路由器
  4. 在自动化之前手动测试命令
  5. 维护路由器配置的备份

故障排除

连接问题

# 手动测试 SSH 连接
ssh admin@192.168.1.1

# 检查路由器是否启用了 SSH
# 通过 Web 界面：管理 > 系统 > 启用 SSH

权限被拒绝

# 确保 SSH 密钥可读
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub

# 验证密钥已添加到路由器
ssh admin@192.168.1.1 "cat /tmp/home/root/.ssh/authorized_keys"

导入错误

# 确保虚拟环境已激活
source venv/bin/activate

# 重新安装依赖项
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 配置文件不扩展如 ${HOME} 或 ~ 这样的 shell 变量。

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

// 错误 - 不会工作：
"-v", "${HOME}/.ssh:/home/mcpuser/.ssh:ro"

// 正确 - 使用绝对路径：
"-v", "/home/triskull/.ssh:/home/mcpuser/.ssh:ro"

要找到您的主目录：

echo $HOME
# 输出：/home/triskull