# mcp-vps-monitor

一个专为 AI 智能体（如 OpenClaw / 小龙虾、Cursor、Claude Desktop 等）设计的通用 VPS 系统监测与运维 MCP（Model Context Protocol）工具包。

本工具包采用**纯只读架构**，支持数据缓存防高并发打爆 CPU、正则表达式防命令注入，并提供精准的内存/Swap 统计与 Docker 容器运行状态排查。

---

## 🛠️ 项目结构

```text
mcp-vps-monitor/
├── src/
│   └── index.ts        # MCP 服务核心源码（已优化缓存与安全校验）
├── dist/               # 自动编译生成的 JavaScript 运行目录
├── package.json        # 项目依赖配置
├── tsconfig.json       # TypeScript 编译选项
├── setup.sh            # Linux / VPS 环境一键部署脚本
├── init.bat            # Windows 本地环境一键部署脚本
└── README.md           # 部署使用说明文档

```

---

## 🛠️ 核心功能列表 (Tools)

| 工具名称 | 功能描述 | 特性与安全防护 | 示例输入参数 |
| --- | --- | --- | --- |
| `get_system_metrics` | 获取 CPU 占用、精准可用内存（Available）、Swap 交换分区以及磁盘容量信息 | 具备 3 秒 In-Memory 缓存，防止智能体高频调用打爆 CPU | 无 |
| `check_network_ping` | 测试 VPS 到指定目标 IP 或域名的网络延迟与连通性 | 内置严格正则匹配校验，防范命令行注入攻击 | `{"host": "1.1.1.1"}` |
| `get_top_processes` | 获取当前系统 CPU 或内存占用最高的前 N 个进程 | 经过字段精简脱敏，减少 Token 消耗 | `{"limit": 5}` |
| `get_docker_status` | 获取 VPS 上运行的 Docker 容器列表及其运行状态 | 快速提取容器 ID、名称、镜像与 Up/Exited 状态 | 无 |

---

## 🚀 部署与初始化步骤

### 环境要求

* **Node.js**：v18.0.0 或更高版本
* **npm**：随 Node.js 一起安装

---

### 途径一：在 Linux / VPS 环境部署（推荐）

1. **上传项目文件**：
将 `mcp-vps-monitor` 文件夹上传至 VPS 的任意目录（例如 `/opt/mcp-vps-monitor`）。
2. **运行一键部署脚本**：
进入项目目录并执行 `setup.sh` 脚本，自动安装依赖并完成编译：
```bash
cd /opt/mcp-vps-monitor
bash setup.sh

```


3. **运行结果校验**：
脚本执行完成后，会在项目根目录下生成 `dist/index.js` 文件。

---

### 途径二：在 Windows 本地电脑部署

1. **打开项目目录**：
进入 `mcp-vps-monitor` 根目录。
2. **双击运行脚本**：
直接双击运行 `init.bat` 脚本。
3. **运行结果校验**：
脚本会自动唤起命令行界面进行 `npm install` 与 `npx tsc` 编译，完成后按下任意键退出即可。

---

## 🤖 智能体（Agent）接入配置

### 接入 OpenClaw（小龙虾）

OpenClaw 与 MCP 服务部署在同一台 VPS 环境下时，建议采用 **STDIO 管道传输** 模式接入。

1. 打开 OpenClaw 的配置文件（例如 `openclaw.json` 或 Agent 配置文件）。
2. 在 `mcpServers` 字段中添加以下配置节点：

```json
{
  "mcpServers": {
    "vps-monitor": {
      "command": "node",
      "args": [
        "/opt/mcp-vps-monitor/dist/index.js"
      ]
    }
  }
}

```

> **注意**：请确保 `/opt/mcp-vps-monitor/dist/index.js` 为您 VPS 上的实际绝对路径。

3. 保存配置文件并重启 OpenClaw 服务。

---

## ❓ 常见问题与注意事项

1. **Docker 容器列表获取失败**：
* **原因**：运行 MCP 服务或 OpenClaw 的系统用户缺乏读取 Docker Daemon 的权限。
* **解决方案**：请使用 `root` 用户运行，或将当前非 root 用户加入 docker 用户组：
```bash
sudo usermod -aG docker $USER

```




2. **网络 Ping 测试提示格式非法**：
* **原因**：`check_network_ping` 增加了正则安全过滤，仅支持标准的 IP 地址（如 `1.1.1.1`）或域名（如 `google.com`），不支持带空格或管道符的复杂字符串。