Which integrations are available for this server?

Provides monitoring of AdGuardHome status on the router, including query counts, blocked queries, and top domains. Provides Docker status monitoring, including container list, version, and disk usage. Provides comprehensive read-only monitoring of OpenWRT/iStoreOS routers, including system status, network info, logs, and plugin status.

How do I use iStoreOS MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@iStoreOS MCP Server show me the current CPU and memory usage" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

iStoreOS MCP Server

by beck-8

Overview Schema Source Related Servers Discussions Admin

Python

Local

iStoreOS MCP Server

English | 中文

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

Related MCP server: MCP SSH SRE

快速开始

安装

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

Available Tools

31 tools

get_active_connectionsA

Get active network connections from conntrack table (protocol, src, dst, ports, state). Use 'limit' to cap results (default 500)

Inputs: limit. Returns: result

get_adguardhome_statusA

Get AdGuardHome status: running, protection enabled, DNS queries total/blocked, top domains/clients