OpenWrt MCP Server

一个用于操作 OpenWrt 路由器设备的 MCP (Model Context Protocol) Server。通过 SSH 连接到路由器，提供丰富的工具集来管理和开发 OpenWrt 设备。

功能

连接管理

• connect_router — 通过 SSH 连接到 OpenWrt 路由器
• disconnect_router — 断开当前连接
• connection_status — 查看连接状态

命令执行

• run_command — 在路由器上执行任意 shell 命令

UCI 配置管理

• uci_show — 查看 UCI 配置
• uci_get — 获取指定配置值
• uci_set — 设置配置值
• uci_add — 添加匿名配置节
• uci_delete — 删除配置节或选项
• uci_add_list / uci_del_list — 列表操作
• uci_commit — 提交更改（可选重启服务）
• uci_changes — 查看未提交的更改
• uci_revert — 撤销更改

网络管理

• network_interfaces — 列出所有网络接口
• network_status — 查看指定接口状态
• wifi_status — 查看无线状态
• wifi_scan — 扫描附近无线网络
• connected_clients — 查看已连接客户端
• network_restart — 重启网络服务
• firewall_status — 查看防火墙规则
• ping_test — 从路由器 ping 测试
• dns_lookup — DNS 查询
• route_table — 查看路由表

系统管理

• system_info — 获取系统综合信息
• system_log — 查看系统日志
• kernel_log — 查看内核日志
• process_list — 查看运行进程
• service_list — 列出服务及状态
• service_action — 管理服务（启动/停止/重启/启用/禁用）
• system_reboot — 重启路由器
• cron_list — 查看定时任务

文件操作

• file_read — 读取文件内容
• file_write — 写入文件
• file_list — 列出目录内容
• file_delete — 删除文件
• file_search — 搜索文件或文件内容
• file_chmod — 修改文件权限

包管理 (opkg)

• opkg_update — 更新软件包列表
• opkg_list — 列出可用/已安装软件包
• opkg_install — 安装软件包
• opkg_remove — 移除软件包
• opkg_info — 查看软件包详情
• opkg_upgradable — 列出可升级的软件包

安装

npm install
npm run build

运行模式

模式一：本地 Stdio（默认）

通过标准输入输出通信，适合本机 MCP 客户端直接调用：

npm start
# 或
node dist/index.js

模式二：远程 HTTP/SSE

启动 HTTP 服务器，允许远程客户端通过 SSE 协议连接：

npm run start:http
# 或
node dist/index.js --http

环境变量：

• MCP_PORT — 监听端口（默认 3000）
• MCP_HOST — 监听地址（默认 0.0.0.0）
• MCP_PASSWORD — OAuth 认证密码（默认 openwrt）
• MCP_BASE_URL — 对外基础 URL（用于 OAuth 回调，默认自动推断）

# 示例：指定端口、地址和密码
MCP_PORT=8080 MCP_PASSWORD=mysecret node dist/index.js --http

端点说明：

• POST /mcp — Streamable HTTP 端点（Claude Code 首选）
• GET /sse — SSE 连接端点
• POST /messages?sessionId=xxx — SSE 消息发送端点
• GET /health — 健康检查
• GET /oauth/authorize — OAuth 认证页面
• POST /oauth/token — Token 端点

配置

在 MCP 客户端（如 Windsurf、Claude Desktop）中添加以下配置：

本地模式 — Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "openwrt": {
      "command": "node",
      "args": ["<项目绝对路径>/dist/index.js"]
    }
  }
}

本地模式 — Claude Desktop

{
  "mcpServers": {
    "openwrt": {
      "command": "node",
      "args": ["<项目绝对路径>/dist/index.js"]
    }
  }
}

远程模式 — 客户端 SSE 连接

先在服务器上启动 HTTP 模式：

node dist/index.js --http

然后在支持 SSE 传输的 MCP 客户端中配置：

Claude Code

claude mcp add openwrt --transport sse http://10.118.81.110:6666/sse

或编辑 ~/.claude/settings.json：

{
  "mcpServers": {
    "openwrt": {
      "type": "sse",
      "url": "http://10.118.81.110:6666/sse"
    }
  }
}

Windsurf / Claude Desktop（远程）

{
  "mcpServers": {
    "openwrt": {
      "url": "http://<服务器IP>:3000/sse"
    }
  }
}

使用示例

1. 先连接到路由器：

   连接到我的路由器 192.168.1.1，用户名 root，密码 arcwrt

2. 查看系统信息：

   获取路由器的系统信息

3. 配置网络：

   把 LAN 口的 IP 改为 192.168.2.1

4. 安装软件包：

   安装 luci-app-openclash

5. 查看日志：

   查看最近的系统日志，过滤包含 error 的条目

开发

npm run watch    # 监听模式编译
npm run dev      # 使用 ts-node 直接运行

技术栈

• TypeScript — 类型安全
• @modelcontextprotocol/sdk — MCP 协议实现
• ssh2 — SSH 连接
• zod — 参数校验

许可证

MIT