Asuswrt Mcp Server

AsusWRT MCP 服务

mcp-name: io.github.teefloo/asuswrt-mcp

通过 SSH 安全、可控地管理 AsusWRT 和 AsusWRT-Merlin 路由器的 Model Context Protocol（MCP）服务。

概览

此 MCP 服务为 AI 助手（如 Claude、Cursor 等）提供安全的接口，用于监控和管理 AsusWRT 路由器。它仅通过 SSH 使用允许列表中的操作，不会执行任意命令、修改固件或恢复出厂设置。

功能

只读监控（42 个工具）

类别	工具
身份与运行状况	路由器型号、固件版本、运行时间、负载、内存
网络	LAN/WAN 详情、DNS 配置、IPv6 状态、路由表
客户端	已连接客户端、DHCP 租约、ARP 邻居
无线网络	无线电状态、SSID、访客网络、各频段的客户端数量
服务	运行中的进程、开放端口、cron 作业
存储	USB 设备、挂载、分区、文件系统用量
安全	UPnP、DDNS、Samba 状态、conntrack 用量
VPN	OpenVPN 服务端、WireGuard、VPN 客户端配置文件
管理	Web 管理端口、SSH/telnet 访问设置
诊断	SSH TCP/横幅/身份验证诊断、配置快照

修改工具（带安全防护）

所有修改工具都需要：

• confirm: true 参数
• ASUSWRT_ALLOW_MUTATIONS=true 环境变量
• 支持使用 dry_run: true 预览更改

工具	说明
asuswrt_restart_service	重启允许列表中的服务（httpd、firewall、wireless、dnsmasq 等）
asuswrt_dhcp_server	启用/禁用 DHCP 服务端
asuswrt_upnp	启用/禁用 UPnP
asuswrt_radio	启用/禁用 Wi-Fi 无线电频段
asuswrt_guest_wifi	启用/禁用访客 Wi-Fi
asuswrt_guest_lan_access	切换访客 Wi-Fi 的 LAN 访问权限
asuswrt_port_forwarding	列出、添加、移除、启用/禁用端口转发规则
asuswrt_vpn_server	启用/禁用 OpenVPN 服务端
asuswrt_parental_access	列出、阻止、解除阻止、移除家长控制规则
asuswrt_parental_block_all	切换全部阻止模式
asuswrt_dhcp_reservation	列出、添加、移除 DHCP 静态预留

安全模型

• 不执行任意 SSH 命令：仅通过 NVRAM 和服务调用执行允许列表中的命令
• 不执行固件操作：不访问闪存、重置或引导加载程序
• 隐去机密信息：工具响应绝不暴露密码和敏感数据
• 支持试运行：每项修改都可在应用前预览
• 需要确认：修改必须显式设置 confirm=True
• 仅使用 SSH 传输：不暴露路由器的 Web API

前提条件

• Python 3.11+
• 已启用 SSH 访问的 AsusWRT 或 AsusWRT-Merlin 路由器
• MCP 客户端与路由器之间的网络连接

安装

1. 克隆并设置

git clone https://github.com/Teeflo/asuswrt-mcp.git
cd asuswrt-mcp

# Create virtual environment
python -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Install dependencies
pip install -e .

2. 配置环境

# Copy example configuration
cp .env.example .env

# Edit with your router credentials
# Use your favorite editor:
notepad .env        # Windows
nano .env           # Linux/macOS

3. 配置 .env

# Required: Router connection
ASUSWRT_HOST=192.168.1.1
ASUSWRT_SSH_USERNAME=admin
ASUSWRT_SSH_PASSWORD=your_password

# Optional: SSH key authentication
# ASUSWRT_SSH_KEY_FILE=~/.ssh/id_rsa

# Optional: Enable mutations (disabled by default)
# ASUSWRT_ALLOW_MUTATIONS=true

# Optional: Connection settings
# ASUSWRT_SSH_PORT=22
# ASUSWRT_TIMEOUT_SECONDS=10

使用方法

运行 MCP 服务

# Standard stdio mode
python -m asuswrt_mcp.server

# Or use the entry point
asuswrt-mcp

在 Claude Desktop / Cursor 中配置

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "asuswrt-mcp": {
      "command": "C:\\path\\to\\asuswrt-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "asuswrt_mcp.server"],
      "env": {
        "ASUSWRT_HOST": "192.168.1.1",
        "ASUSWRT_SSH_USERNAME": "admin",
        "ASUSWRT_SSH_PASSWORD": "your_password"
      }
    }
  }
}

使用 npx Inspector（开发）

npx @modelcontextprotocol/inspector python -m asuswrt_mcp.server

开发

运行测试

pip install -e ".[dev]"
pytest

运行实时路由器集成测试

ASUSWRT_TEST_ROUTER=1 pytest

项目结构

asuswrt-mcp/
├── src/asuswrt_mcp/
│   ├── server.py          # FastMCP entrypoint & tool definitions
│   ├── service.py         # Business logic & router operations
│   ├── config.py          # Settings management
│   ├── clients/
│   │   └── ssh.py         # SSH client wrapper
│   ├── nvram.py           # NVRAM parsing utilities
│   ├── ssh_parsers.py     # Output parsers for SSH commands
│   ├── security.py        # Mutation guards & redaction
│   ├── validators.py      # Input validation
│   ├── responses.py       # Tool response formatting
│   ├── errors.py          # Custom exceptions
│   └── serialization.py   # Safe serialization
├── tests/                 # Test suite (69 tests)
├── .env.example           # Example configuration
├── pyproject.toml         # Project metadata
└── README.md              # This file

许可证

MIT License - 详情请参见 LICENSE。

致谢

• 感谢 asusrouter 提供底层 Python 库
• 感谢 MCP 提供协议规范
• 感谢 AsusWRT-Merlin 提供固件