# iStoreOS MCP Server

**Version:** 0.1.0  
**Author:** [beck-8](https://github.com/beck-8)  
**Date:** April 02, 2026  
**License:** MIT License

## 概览

MCP server for iStoreOS/OpenWRT router monitoring (read-only). Connects via SSH or HTTP/ubus API. Configure connection parameters via environment variables such as ISTOREOS_HOST, ISTOREOS_SSH_PASSWORD, ISTOREOS_SSH_KEY, ISTOREOS_HTTP_PASSWORD.

---

iStoreOS/OpenWRT 路由器只读监控 [MCP](https://modelcontextprotocol.io/) 服务器。

通过 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 的系统

## 快速开始

### 安装

```bash
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_config.json` 中添加：

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

直接运行：

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

## 连接方式说明

### SSH (推荐)

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

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

```bash
# 密码认证
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 连接。

## 可用工具 (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 运行状态、服务器配置、代理隧道 |

## 项目结构

```plaintext
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](https://github.com/beck-8/istoreos-mcp)

---

## English

A read-only [MCP](https://modelcontextprotocol.io/) 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

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

### Compatibility

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