OpenWRT SSH MCP Server

OpenWRT SSH MCP服务器🐳

一个容器化的MCP（模型上下文协议）服务器，用于通过SSH管理OpenWRT路由器。该服务器允许AI代理（如Claude）远程安全地执行命令和管理OpenWRT路由器。

🎉 状态: ✅ 功能齐全，经过物理路由器测试

✨ 特性

• 🐳 Docker就绪 -多级构建的优化映像（271MB）
• 🔐 鲁棒安全 -命令白名单、只读文件系统、审计日志
• 🛠️ 19 OpenWRT工具 -完整的路由器管理（网络、系统、线程、包）
• 🚀 易于集成 -与Claude Desktop和VS Code兼容
• 📊 监控 -所有操作的详细日志
• 🔄 MCP工具包 -与Docker桌面MCP完全兼容
• 📦 包管理 -使用opkg安装/删除IPK软件包
• 🔗 OpenThread OTBR -支持线程边界路由器

建筑

┌─────────────────────┐
│ Claude / VS Code    │  ← Your AI agent
└──────────┬──────────┘
           │ MCP Protocol (stdio)
           │
┌──────────▼──────────┐
│ Docker Container    │  ← MCP Server
│  ┌──────────────┐   │
│  │ MCP Server   │   │
│  │ (Python)     │   │
│  └──────┬───────┘   │
└─────────┼───────────┘
          │ SSH
          │
┌─────────▼───────────┐
│ OpenWRT Router      │  ← Your physical router
│ (192.168.1.1)       │
└─────────────────────┘

特性

• 🔐 安全SSH身份验证（基于密码或密钥）
• 🛠️ OpenWRT专用工具（ubus、uci）
• ✅ 使用白名单进行命令验证
• 📝 审核日志记录
• 🐳 Docker支持（可选）
• 🔌 与Claude Desktop和VS Code集成

需求

• Python 3.10+
• 启用SSH的OpenWRT路由器
• SSH访问路由器（建议root用户）

安装

1.克隆或创建项目

cd "c:\Users\Luis Antonio\Documents\UNAL\MCPs-OpenWRT"

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

python -m venv venv
.\venv\Scripts\activate  # Windows
pip install -e .

3.配置SSH凭据

# Copy example file
copy .env.example .env

# Edit .env with your router credentials

4.生成并复制SSH密钥（推荐）

# Generate dedicated key
ssh-keygen -t ed25519 -f ~/.ssh/openwrt_router -C "MCP Server"

# Copy to router
ssh-copy-id -i ~/.ssh/openwrt_router.pub root@192.168.1.1

# Update .env
OPENWRT_KEY_FILE=C:\Users\YOUR_USER\.ssh\openwrt_router

🔧 配置

克劳德桌面（Docker）

包括优化的配置 claude_desktop_config.json:

{
  "mcpServers": {
    "openwrt-router-docker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network", "host",
        "--env-file", "C:\\Users\\Luis Antonio\\Documents\\UNAL\\MCPs-OpenWRT\\.env",
        "--mount", "type=bind,src=C:\\Users\\Luis Antonio\\.ssh,dst=/root/.ssh,readonly",
        "openwrt-ssh-mcp:latest"
      ]
    }
  }
}

VS代码与GitHub Copilot

该项目包括完整的VS代码配置：

选项1：直接使用Python（推荐）

# Open workspace
code mcp-openwrt.code-workspace

# In Copilot Chat (Ctrl+Shift+I):
"What OpenWRT tools do I have available?"

选项2：带任务

Terminal > Run Task > "Start MCP Server (Python)"

选项3：启动脚本

.\start-mcp-vscode.ps1

脚本助手

使用 docker-mcp.ps1 对于所有操作：

.\docker-mcp.ps1 build   # Build image
.\docker-mcp.ps1 run     # Run server
.\docker-mcp.ps1 test    # Test connection
.\docker-mcp.ps1 logs    # View logs
.\docker-mcp.ps1 shell   # Open shell
.\docker-mcp.ps1 clean   # Clean all

🛠️ 可用工具

系统和网络（8个工具）

• openwrt_test_connection -测试SSH连接
• openwrt_execute_command -执行原始命令（已验证）
• openwrt_get_system_info -系统信息（正常运行时间、内存、CPU）
• openwrt_restart_interface -重新启动网络接口
• openwrt_get_wifi_status -WiFi状态和客户端
• openwrt_list_dhcp_leases -列出DHCP客户端
• openwrt_get_firewall_rules -查看防火墙规则
• openwrt_read_config -读取UCI配置文件

OpenThread边界路由器（5个工具）

• openwrt_thread_get_state -当前线程状态
• openwrt_thread_create_network -创建新的Thread网络
• openwrt_thread_get_dataset -获取网络凭据
• openwrt_thread_get_info -完整的Thread网络信息
• openwrt_thread_enable_commissioner -允许新设备

包管理（6个工具）

• openwrt_opkg_update -更新包列表
• openwrt_opkg_install -安装IPK软件包
• openwrt_opkg_remove -删除包
• openwrt_opkg_list_installed -列出已安装的软件包
• openwrt_opkg_info -详细的包裹信息
• openwrt_opkg_list_available -列出可用包

💬 使用示例

配置后，您可以询问Claude：

系统与网络

• “显示路由器上的WiFi状态”
• “列出连接的设备”
• “重新启动广域网接口”
• “路由器的内存使用情况如何？”

包管理

• “更新包存储库”
• “安装luci应用程序openthread包”
• “显示已安装的软件包”
• “给我有关ot-br posix包的信息”

OpenThread

• 在频道15上创建一个名为“MyHome”的Thread网络
• “显示Thread网络状态”
• “允许专员添加新设备”
• “给我Thread网络凭据”

安全

⚠️ 重要：此服务器具有对路由器的root访问权限。确保：

• 使用SSH密钥身份验证（不是密码）
• 保持 .env 版本控制之外
• 生产执行前审查命令
• 启用审核日志记录
• 限制从路由器到PC的SSH访问

📚 文档

🚀 快速开始

• 快速启动_医生.md -Docker快速入门
• TEST_OPKG.md -测试IPK包管理

📖 详细指南

• **** -完整的Docker指南

🧪 测试

# Test with helper script
.\docker-mcp.ps1 test

# Test with MCP Inspector
npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector docker run -i --rm openwrt-ssh-mcp:latest

# View logs
.\docker-mcp.ps1 logs

🔐 已实施的安全

• ✅ 只读文件系统 -不可变容器
• ✅ 没有能力 -无特殊权限
• ✅ SSH密钥只读 -受保护的密钥
• ✅ 命令白名单 -只有安全命令
• ✅ 审核日志记录 -完成日志记录
• ✅ 易失性tmpfs -重新启动时已清理/tmp
• ✅ 无特权升级 -没有sudo

🎯 用例

高级工作流

• 🔄 自动备份 UCI配置
• 📊 网络监控 -连接的设备、资源使用情况
• 🔧 AI引导的故障排除
• 📝 自动文档 变化
• 🚨 网络异常警报
• 📦 程序包管理 -安装/更新软件
• 🔗 线程配置 -创建和管理线程/物质网络
• 🛡️ 安全审计 -查看防火墙规则

🐳 Docker Hub（可选）

# Publish your image
docker login
docker tag openwrt-ssh-mcp:latest yourusername/openwrt-ssh-mcp:latest
docker push yourusername/openwrt-ssh-mcp:latest

🛠️ 发展

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
ruff check --fix .

# Rebuild after changes
.\docker-mcp.ps1 build

🤝 贡献

欢迎投稿！拜托：

1. 分叉项目
2. 为您的功能创建分支
3. 提交您的更改
4. 推到分支
5. 打开拉取请求

📖 资源

• MCP文件
• OpenWRT文档
• MCP服务器存储库

📄 许可证

麻省理工学院

______________________________________________________________________

由...制作❤️ 面向OpenWRT和MCP社区