VPS Server

FreeNot checked

Enables remote command execution, scripting, file operations, and persistent tmux sessions on a VPS via MCP protocol.

by zhy1369800

GitHub Embed

About

Enables remote command execution, scripting, file operations, and persistent tmux sessions on a VPS via MCP protocol.

README

English | 中文说明

English Description

An advanced Model Context Protocol (MCP) server designed to turn your VPS into a powerful AI-driven remote workstation. It provides a comprehensive set of tools for command execution, file management, system monitoring, and persistent session handling.

🌟 Key Features

Command Execution: Run shell commands and scripts (Python/Node/Bash) in a sandboxed environment.
Advanced File Management: Read, write, patch, search, and visualize directory trees.
Persistent Sessions: Based on tmux, allowing AI to handle long-running or interactive tasks.
System Monitoring: Real-time process listing and system resource tracking.
Network Capabilities: Make HTTP requests or download large files directly to the VPS.
Flexible Transport: Supports both stdio and SSE (HTTP) modes.

⚡️ Quick Run with npx

You can run the server directly without cloning the repository:

# stdio mode (for local use)
npx github:zhy1369800/vps-mcp-server

# SSE mode (for remote VPS deployment)
MODE=sse PORT=8080 MCP_TOKEN=your-token npx github:zhy1369800/vps-mcp-server

🛠 Tools Reference

Tool	Description
`run_command`	Execute a one-off shell command.
`run_script`	Run Python, Bash, or Node.js code blocks.
`list_files`	List directory contents or generate a recursive tree.
`file_read/write`	Read from or write to files.
`file_patch`	Edit specific parts of a file (Token-efficient).
`file_search`	Search for files by name or content (grep).
`get_system_status`	Get OS info, memory, disk, or process list.
`http_request`	Fetch web content or download files to disk.
`session_*`	Start, exec, read, or stop persistent `tmux` sessions.

🚀 Manual Installation

Clone & Install:

git clone https://github.com/zhy1369800/vps-mcp-server.git
cd vps-mcp-server
npm install

Build:
```
npm run build
```
Configure: Copy .env.example to .env and set your MCP_TOKEN.
Run (SSE Mode):
```
MODE=sse PORT=8080 npm start
```

中文说明

这是一个先进的 Model Context Protocol (MCP) 服务端，旨在将您的 VPS 变成一个强大的 AI 驱动远程工作站。它为 AI Agent 提供了完整的指令执行、文件管理、系统监控和持久化会话处理工具集。

🌟 核心特性

指令执行：在沙箱环境中运行 Shell 命令和脚本（Python/Node/Bash）。
高级文件管理：支持读取、写入、增量补丁（Patch）、全文搜索及目录树可视化。
持久化会话：基于 tmux 实现，允许 AI 处理耗时较长或需要交互的任务。
系统监控：实时查看进程列表、CPU、内存及磁盘占用情况。
网络增强：直接从 VPS 发起 HTTP 请求或下载大文件到磁盘。
双模式支持：支持 stdio 本地调用和 SSE (HTTP) 远程调用模式。

⚡️ 使用 npx 快速运行

无需克隆代码即可直接启动服务：

# stdio 模式 (本地使用)
npx github:zhy1369800/vps-mcp-server

# SSE 模式 (远程 VPS 部署)
MODE=sse PORT=8080 MCP_TOKEN=your-token npx github:zhy1369800/vps-mcp-server

🛠 工具列表

工具名称	功能描述
`run_command`	执行一次性 Shell 命令。
`run_script`	运行 Python、Bash 或 Node.js 代码块。
`list_files`	列出目录内容或生成递归目录树（支持排除目录）。
`file_read/write`	读取或写入文件。
`file_patch`	增量编辑文件特定部分（极度节省 Token）。
`file_search`	按名称或内容搜索文件（基于 grep）。
`get_system_status`	获取系统概览、内存、磁盘或进程列表。
`http_request`	发起 HTTP 请求或下载文件到 VPS 磁盘。
`session_*`	启动、执行、读取或停止持久化的 `tmux` 会话。

🚀 手动安装步骤

克隆与安装：

git clone https://github.com/zhy1369800/vps-mcp-server.git
cd vps-mcp-server
npm install

编译：
```
npm run build
```
配置环境：将 .env.example 复制为 .env 并设置您的 MCP_TOKEN。
启动服务 (SSE 模式)：
```
MODE=sse PORT=8080 npm start
```

🛡 安全建议

建议在 Docker 容器中运行此服务，并配合 Nginx 反向代理（配置 SSL 证书）以确保通信安全。

📄 开源协议

MIT

from github.com/zhy1369800/vps-mcp-server

Install VPS Server in Claude Desktop, Claude Code & Cursor

Recommended · one command, every IDE

unyly install vps-mcp-server

Installs into Claude Desktop, Claude Code, Cursor & VS Code — handles npx, uvx and build-from-source repos for you.

First time? Get the CLI: curl -fsSL https://unyly.org/install | sh

Or configure manually

Run in your terminal:

claude mcp add vps-mcp-server -- npx -y @zy_zhou/vps-mcp-server

FAQ

Is VPS Server MCP free?

Yes, VPS Server MCP is free — one-click install via Unyly at no cost.

Does VPS Server need an API key?

No, VPS Server runs without API keys or environment variables.

Is VPS Server hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install VPS Server in Claude Desktop, Claude Code or Cursor?

Open VPS Server on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Related MCPs

GitHub

PRs, issues, code search, CI status

by GitHub

Filesystem

Secure file operations with configurable access controls.

by Community

Memory

Knowledge graph-based persistent memory system.