AI导哈

VPS远程管理服务器

通过SSH为AI助手提供对VPS的完全控制，包括执行命令、管理文件、控制服务、监控资源、管理Docker容器和配置防火墙等功能。

  • by harbouli
  • TypeScript
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 harbouli/vps-mcp-server

使用说明

🖥️ VPS MCP服务器

一 MCP（模型上下文协议） 服务器，让AI助手通过SSH完全控制VPS。通过安全的SSH隧道执行命令、管理文件、控制服务、监控资源、管理Docker容器和配置防火墙。

✨ 特性

工具 说明
run_command 在VPS上执行任何shell命令
read_file 通过SFTP读取文件内容
write_file 通过SFTP创建或覆盖文件
list_directory 列出目录内容及详细信息
manage_service 启动、停止、重新启动、重新加载、启用、禁用systemd服务和查看日志
list_services 列出按状态筛选的systemd服务（正在运行、失败、已启用）
system_stats 获取CPU、内存、磁盘、网络、正常运行时间和进程统计数据
docker 管理Docker容器——列表、启动、停止、重启、日志、统计数据、图像
firewall 管理UFW规则——状态、允许、拒绝、删除、重置

📦 安装

# Clone the repository
git clone https://github.com/your-username/vps-mcp-server.git
cd vps-mcp-server

# Install dependencies
pnpm install

# Build
pnpm build

⚙️ 配置

创建一个 .env 示例中的文件：

cp .env.example .env

设置以下环境变量：

变量 必填 默认 描述
VPS_HOST ✅ — 您的VPS的主机名或IP
VPS_USER ✅ — SSH用户名
VPS_KEY_PATH ✅ — SSH私钥的绝对路径
VPS_PORT ❌ 22 SSH端口
VPS_KEY_PASSPHRASE ❌ — SSH密钥的密码（如果已加密）

示例 .env:

VPS_HOST=203.0.113.10
VPS_USER=deploy
VPS_KEY_PATH=/Users/you/.ssh/id_ed25519
VPS_PORT=22

🚀 用法

使用Claude Desktop/Gemini CLI/任何MCP客户端

将服务器添加到MCP客户端配置中：

{
  "mcpServers": {
    "vps": {
      "command": "node",
      "args": ["/absolute/path/to/vps-mcp-server/dist/index.js"],
      "env": {
        "VPS_HOST": "203.0.113.10",
        "VPS_USER": "deploy",
        "VPS_KEY_PATH": "/Users/you/.ssh/id_ed25519"
      }
    }
  }
}

开发模式

pnpm dev

生产

pnpm build
pnpm start

🛠️ 工具参考

run_command

在VPS上执行shell命令。

参数 类型 必填 默认 说明
command string ✅ — 要执行的shell命令
timeout number ❌ 30000 超时（毫秒）
working_directory string ❌ — 运行命令的目录

退货： JSON格式 exit_code, stdout，以及 stderr.

read_file

通过SFTP读取VPS上文件的内容。

参数 类型 必填 默认 说明
path string ✅ — 文件的绝对路径
max_lines number ❌ — 要返回的最大行数（完整文件省略）

write_file

通过SFTP将内容写入VPS上的文件。

参数 类型 必填 默认 说明
path string ✅ — 文件的绝对路径
content string ✅ — 要写的内容
create_dirs boolean ❌ false 如果缺少，则创建父目录

list_directory

列出给定路径下的文件和目录。

参数 类型 必填 默认 说明
path string ❌ / 列表的目录路径
show_hidden boolean ❌ false 包含点文件
long_format boolean ❌ true 显示权限、大小、日期

manage_service

管理systemd服务。

参数 类型 必填 默认 说明
service string ✅ — 服务名称（例如。， nginx)
action enum ✅ — start
log_lines number ❌ 50 要显示的线条（用于 logs 行动）

list_services

列出按状态筛选的systemd服务。

参数 类型 必填 默认 说明
filter enum ❌ running all

system_stats

获取系统资源使用情况。

参数 类型 必填 默认 说明
include array ❌ ["all"] cpu

docker

管理Docker容器。

参数 类型 必填 默认 说明
action enum ✅ — ps
container string ❌ — 容器名称/ID（必需 start/stop/restart/logs)
log_lines number ❌ 50 要显示的线条（用于 logs 行动）

firewall

管理UFW防火墙规则。

参数 类型 必填 默认 说明
action enum ✅ — status
rule string ❌ — 规则规范（例如。， 80/tcp, 443, from 10.0.0.1)

📁 项目结构

src/
├── index.ts            # Server bootstrap & lifecycle
├── ssh.ts              # SSHManager class (connection pooling)
├── types.ts            # Shared TypeScript types
├── helpers.ts          # Response helper functions
└── tools/
    ├── index.ts         # Tool registration barrel
    ├── run-command.ts   # Shell command execution
    ├── read-file.ts     # SFTP file reading
    ├── write-file.ts    # SFTP file writing
    ├── list-directory.ts
    ├── manage-service.ts
    ├── list-services.ts
    ├── system-stats.ts
    ├── docker.ts
    └── firewall.ts

🔒 安全说明

  • 服务器使用SSH连接 基于密钥的身份验证 （无密码）。
  • 命令以配置的SSH用户的权限运行。
  • 服务管理和防火墙工具的使用 sudo --确保您的SSH用户具有适当的sudoers权限。
  • 服务器保持一个持久的SSH连接，如果断开，该连接会自动重新连接。

📄 许可证

麻省理工学院

相关 MCP