iStoreOS MCP Server

---

iStoreOS/OpenWRT 路由器只读监控 MCP 服务器。

通过 SSH 或 HTTP/ubus API 连接路由器，为 AI 助手提供路由器状态数据的读取能力。可对接 Claude Desktop、Claude Code、小龙虾等 MCP 客户端，实现在手机/电脑上通过自然语言查看路由器状态、分析日志、排查网络问题。

功能特性

31 个只读工具，覆盖系统、网络、日志、服务、常见插件
双连接模式：SSH（全功能）+ HTTP/ubus API
插件感知：自动检测 OpenClash、Passwall、AdGuardHome、Samba、DDNS、FRP 等常见插件状态
安全设计：只读操作，不修改路由器配置；输入参数经过校验和转义
兼容性好：支持 iStoreOS、OpenWRT 21.02+ 及其他基于 OpenWRT 的系统

快速开始

安装

git clone https://github.com/beck-8/istoreos-mcp.git
cd istoreos-mcp
pip install -e .

配置

通过环境变量配置连接参数：

| 变量 | 默认值 | 说明 | |------|--------|------| | ISTOREOS_HOST | 192.168.1.1 | 路由器 IP 地址 | | ISTOREOS_CONNECTION_TYPE | ssh | 连接方式：ssh 或 http | | ISTOREOS_SSH_PORT | 22 | SSH 端口 | | ISTOREOS_SSH_USER | root | SSH 用户名 | | ISTOREOS_SSH_PASSWORD | - | SSH 密码 | | ISTOREOS_SSH_KEY | - | SSH 私钥文件路径 | | ISTOREOS_HTTP_PORT | 80 | HTTP 端口 | | ISTOREOS_HTTP_PASSWORD | - | rpcd/LuCI 密码 |

Claude Desktop / Claude Code

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "istoreos": {
      "command": "istoreos-mcp",
      "env": {
        "ISTOREOS_HOST": "192.168.1.1",
        "ISTOREOS_CONNECTION_TYPE": "ssh",
        "ISTOREOS_SSH_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add istoreos -- env ISTOREOS_HOST=192.168.1.1 ISTOREOS_SSH_PASSWORD=your-password istoreos-mcp

直接运行

export ISTOREOS_HOST=192.168.1.1
export ISTOREOS_SSH_PASSWORD=your-password
istoreos-mcp

可用工具 (31 个)

系统状态 (6)

| 工具 | 说明 | |------|------| | get_system_info | 固件版本、板型、内核、架构 | | get_cpu_usage | CPU 使用率、负载均值、核心数 | | get_memory_usage | 内存总量/已用/可用/缓存 | | get_storage_usage | 磁盘/闪存各分区使用率 | | get_system_uptime | 系统运行时间 | | get_cpu_temperature | CPU/SoC 温度 |

网络信息 (6)

| 工具 | 说明 | |------|------| | get_network_interfaces | 所有网络接口状态和流量计数 | | get_wan_status | WAN 接口：IP、网关、DNS、连接类型 | | get_connected_devices | 已连接设备列表 (ARP + DHCP 合并) | | get_dhcp_leases | DHCP 租约：MAC、IP、主机名、过期时间 | | get_dns_config | DNS 上游服务器、域名配置 | | get_wifi_status | WiFi 状态：SSID、信道、已连客户端 |

日志与流量 (5)

| 工具 | 说明 | |------|------| | get_system_log | 系统日志，支持 lines 参数限制行数 | | get_kernel_log | 内核日志 (dmesg) | | get_traffic_stats | 各接口 rx/tx 字节、包数、错误、丢包 | | get_active_connections | 活跃连接追踪 (conntrack)，支持 limit 参数 | | get_firewall_rules | 防火墙规则 (nftables/iptables) |

服务与系统管理 (8)

| 工具 | 说明 | |------|------| | get_installed_packages | 已安装软件包，支持 filter_str 过滤 | | get_service_status | 所有 init.d 服务的启用/运行状态 | | get_docker_status | Docker 版本、容器列表、磁盘占用 | | get_block_devices | 块设备、挂载点、文件系统、RAID 状态 | | get_process_list | 运行中进程 (PID/用户/内存/CPU) | | get_port_forwards | 端口转发 / NAT redirect 规则 | | get_crontab | 定时任务列表 | | get_istoreos_mode | iStoreOS 专属：固件版本、iStore 插件、overlay 空间 |

常见插件状态 (6)

| 工具 | 说明 | |------|------| | get_openclash_status | OpenClash：运行状态、代理模式、实时流量、连接数、日志 | | get_passwall_status | Passwall/Passwall2：代理模式、DNS 模式、节点列表 | | get_adguardhome_status | AdGuardHome：查询总数/拦截数/拦截率、热门域名 Top10 | | get_samba_status | Samba：共享目录列表、已连接客户端 | | get_ddns_status | DDNS：配置的服务、域名、更新状态 | | get_frp_status | FRP：frpc/frps 运行状态、服务器配置、代理隧道 |

连接方式说明

SSH (推荐)

所有 31 个工具均可用。OpenWRT 默认开启 SSH，无需额外配置。

支持密码和私钥两种认证方式：

# 密码认证
export ISTOREOS_SSH_PASSWORD=your-password

# 私钥认证
export ISTOREOS_SSH_KEY=~/.ssh/id_rsa

HTTP/ubus

通过 rpcd JSON-RPC 接口连接。仅以下工具可用：

get_system_info
get_network_interfaces
get_wan_status
get_wifi_status

其他依赖 shell 命令的工具会返回提示信息，建议改用 SSH 连接。

使用示例

配置好 MCP 后，可以用自然语言向 AI 助手提问：

"路由器的 CPU 和内存使用率怎么样？"
"有多少设备连接了 WiFi？"
"OpenClash 运行正常吗？有多少活跃连接？"
"看看最近的系统日志，有没有异常？"
"哪个设备的流量最大？"
"AdGuardHome 今天拦截了多少广告？"
"Docker 上跑了哪些容器？"
"检查一下 DDNS 有没有更新成功"

项目结构

src/istoreos_mcp/
├── server.py              # MCP 服务入口，注册所有工具
├── config.py              # 环境变量配置
├── connection/
│   ├── base.py            # 连接抽象接口
│   ├── ssh.py             # SSH 连接 (asyncssh)
│   ├── http.py            # HTTP/ubus JSON-RPC 连接 (httpx)
│   └── factory.py         # 连接工厂
└── tools/
    ├── system.py          # 系统状态工具
    ├── network.py         # 网络信息工具
    ├── logs.py            # 日志与流量工具
    ├── services.py        # 服务管理工具
    └── plugins.py         # 常见插件状态工具

兼容性

| 系统 | 支持状态 | |------|----------| | iStoreOS (所有版本) | 完全支持 | | OpenWRT 21.02+ | 完全支持 | | OpenWRT 19.07 | 基本支持 (部分 nftables 工具不可用) | | 其他基于 OpenWRT 的系统 | 基本支持 |

License

MIT

---

English

A read-only MCP server for monitoring iStoreOS/OpenWRT routers.

Connects to your router via SSH or HTTP/ubus API, providing 31 read-only tools for AI assistants to query system status, network info, logs, traffic, services, and common plugin status (OpenClash, Passwall, AdGuardHome, Samba, DDNS, FRP).

Quick Start

pip install -e .
export ISTOREOS_HOST=192.168.1.1
export ISTOREOS_SSH_PASSWORD=your-password
istoreos-mcp

Claude Desktop Config

{
  "mcpServers": {
    "istoreos": {
      "command": "istoreos-mcp",
      "env": {
        "ISTOREOS_HOST": "192.168.1.1",
        "ISTOREOS_CONNECTION_TYPE": "ssh",
        "ISTOREOS_SSH_PASSWORD": "your-password"
      }
    }
  }
}

Compatibility

iStoreOS (all versions)
OpenWRT 21.02+
Other OpenWRT-based distributions

iStoreOS MCP Server