mcp-vps-monitor

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

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

---

🛠️ 项目结构

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 脚本，自动安装依赖并完成编译：

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 字段中添加以下配置节点：

{
  "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 用户组：

sudo usermod -aG docker $USER

2. 网络 Ping 测试提示格式非法：

• 原因：check_network_ping 增加了正则安全过滤，仅支持标准的 IP 地址（如 1.1.1.1）或域名（如 google.com），不支持带空格或管道符的复杂字符串。