华硕Merlin路由器MCP服务器
模型上下文协议(MCP)服务器,用于通过SSH/SCP管理运行华硕Merlin固件的华硕路由器。
🚨 重大变更-v3.x安全更新
Docker容器现在以无根(非root用户)运行 mcpuser)以增强安全性。
如果从v1.0.0升级到v3.x,您必须用两个更改来更新MCP配置:
| 组件 | v1.0.0(已弃用) | v3.x(当前) |
|---|---|---|
| 容器用户 | root |
mcpuser (UID 1000) |
| 卷装 | ~/.ssh:/root/.ssh:ro |
~/.ssh:/home/mcpuser/.ssh:ro |
| SSH密钥路径 | /root/.ssh/id_rsa |
/home/mcpuser/.ssh/id_rsa |
所需更改:
- 更新卷装载 在Docker参数中:```json
"-v", "~/.ssh:/home/mcpuser/.ssh:ro" // Changed from /root/.ssh
1. **更新环境变量**:```json
"ROUTER_KEY_FILE": "/home/mcpuser/.ssh/id_rsa" // Changed from /root/.ssh/id_rsa
完整的MCP配置示例:```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"
]
}
}
}
**安全优势:**
- ✅ 遵循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密钥身份验证:```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工作站设置```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
## 安装
### 选项1:本地安装(建议用于开发)
1. **克隆或创建项目目录:**```bash
mkdir asus-merlin-mcp
cd asus-merlin-mcp
-
将MCP服务器代码另存为
asus_merlin_mcp.py -
创建虚拟环境并安装依赖关系:```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
1. **配置路由器连接:**```bash
cp .env.example .env
nano .env # Edit with your router details
- 测试连接:```bash
Export environment variables
export $(cat .env | xargs)
Run the server (it will connect via stdio)
python asus_merlin_mcp.py
### 选项2:Docker安装
#### 快速入门-从Docker Hub拉取:```bash
# 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
从源代码构建(替代):
- 构建Docker镜像:```bash
docker build -t asus-merlin-mcp .
1. **使用您的路由器凭据编辑docker-compose.yml**```bash
# Optional -- The credentials are passed to the container via the MCP configurations in Claude or other chatbots.
- 使用Docker Compose运行:```bash
docker-compose up -d
## 克劳德配置
配置位置取决于您使用的Claude安装:
### Claude代码(本地安装)
MCP服务器在中自动配置 `~/.claude.json` 在您的项目路径下:
**配置文件:** `~/.claude.json`
#### 对于本地安装:```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安装:```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"
]
}
}
}
}
}
______________________________________________________________________
### 克劳德代码(NPM安装)
**配置文件:** `~/.claude/settings.json`
#### 对于本地安装:```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安装:```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"
]
}
}
}
______________________________________________________________________
### 克劳德桌面
**配置文件位置:**
- **Linux:** `~/.config/Claude/claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **窗户:** `%APPDATA%\Claude\claude_desktop_config.json`
#### 对于本地安装:```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安装:```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"
]
}
}
}
**重要提示:**
- 替换 `/home/yourusername` 使用您的实际主目录路径(例如。, `/home/triskull`)
- 别用 `${HOME}` 或 `~` 在JSON配置文件中-它们不会展开
- 更新配置文件后,重新启动Claude Code或Claude Desktop以使更改生效
## 用法示例
在Claude Desktop中配置后,您可以与路由器进行交互:
**示例提示:**
- “我的路由器的当前状态如何?”
- “列出所有连接的设备”
- “重新启动无线服务”
- “显示WiFi配置”
- “从NVRAM获取wan_ipadder的值”
- “将此备份脚本上载到/jffs/scripts/”
- “检查VPN是否正在运行”
- “显示路由器的系统日志”
## 可用工具
有关详细的示例提示,请参见 **工具\_ 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` -广域网连接
- `httpd` -Web界面
- `vpnclient1` -VPN客户端1
- `vpnclient2` -VPN客户端2
- `dnsmasq` -DNS/DHCP服务器
## 安全说明
1. **使用SSH密钥而不是密码** 为了更好的安全性
1. **仅在局域网上启用SSH** 除非你需要广域网接入
1. **小心NVRAM操作** -不正确的值可能会损坏路由器
1. **首先手动测试命令** 自动化之前
1. **保留备份** 您的路由器配置
## 故障排除
### 连接问题```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
权限不足```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"
### 导入错误```bash
# 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}` 在配置中使用您的实际主目录路径:```json
// Wrong - will not work:
"-v", "${HOME}/.ssh:/home/mcpuser/.ssh:ro"
// Correct - use absolute path:
"-v", "/home/triskull/.ssh:/home/mcpuser/.ssh:ro"
要查找您的主目录,请执行以下操作:```bash
echo $HOME
Output: /home/triskull
## 如何指导:常见管理任务
本节提供了使用MCP工具执行常见路由器管理任务的实例。
### 管理主机文件
路由器的自定义主机文件(`/jffs/configs/hosts.add`)允许您添加在重新启动后仍然存在的静态DNS条目。
#### 查看当前主机文件
**通过克劳德:**```
"Show me the contents of /jffs/configs/hosts.add"
使用的MCP工具:
read_file
添加新主机条目
选项1:下载、编辑、上传(推荐)
- 下载文件:```
"Download /jffs/configs/hosts.add from the router to ./hosts.add"
*使用: `download_file` 工具*
*注意:下载经过MD5校验和完整性验证*
1. 使用文本编辑器在本地编辑文件:```bash
nano hosts.add
# Add line like:
# 192.168.0.100 newserver.damage.inc newserver
- 上传回路由器:```
"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验证。
更新现有主机条目
- 下载hosts文件
- 在本地编辑以更改所需的行
- 上传回路由器
- 重新启动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. **始终先手动测试命令** 在实现自动化之前
1. **保留备份** 在进行更改之前,请先查看配置文件
1. **使用描述性主机名** 在hosts.add中,便于管理
1. **记录您的自定义脚本** 附有评论
1. **配置更改后重新启动服务** 应用它们
1. **使用SSH密钥** 代替密码以提高安全性
1. **注意NVRAM提交** -不先提交的测试
1. **监控日志** 在做出更改以尽早发现问题后
## 高级用法
### 备份路由器配置```bash
# Via Claude: "Download the router's NVRAM backup"
# This will use the download_file tool to get /jffs/nvram/nvram.txt
上传自定义脚本```bash
Upload a script to run on router boot
Files in /jffs/scripts/ persist across reboots
### 监控路由器运行状况```bash
# Set up periodic checks via cron jobs on the router
# Use the execute_command tool to create cron entries
贡献
请随时使用以下附加工具扩展此MCP服务器:
- 交通监控
- 防火墙规则管理
- 带宽统计
- 端口转发配置
- 访客网络管理
资源
- 华硕梅林维基
- MCP文件
- Paramiko文档
许可证
MIT许可证-使用风险自负。始终维护路由器配置的备份。
