🖥️ VPS MCP Server

An MCP (Model Context Protocol) server that gives AI assistants full control over a VPS via SSH. Execute commands, manage files, control services, monitor resources, manage Docker containers, and configure firewalls — all through a secure SSH tunnel.

✨ Features

Tool	Description
run_command	Execute any shell command on the VPS
read_file	Read file contents via SFTP
write_file	Create or overwrite files via SFTP
list_directory	List directory contents with detailed info
manage_service	Start, stop, restart, reload, enable, disable systemd services & view logs
list_services	List systemd services filtered by state (running, failed, enabled)
system_stats	Get CPU, memory, disk, network, uptime, and process stats
docker	Manage Docker containers — list, start, stop, restart, logs, stats, images
firewall	Manage UFW rules — status, allow, deny, delete, reset

📦 Installation

# 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

⚙️ Configuration

Create a .env file from the example:

cp .env.example .env

Set the following environment variables:

Variable	Required	Default	Description
VPS_HOST	✅	—	Hostname or IP of your VPS
VPS_USER	✅	—	SSH username
VPS_KEY_PATH	✅	—	Absolute path to your SSH private key
VPS_PORT	❌	22	SSH port
VPS_KEY_PASSPHRASE	❌	—	Passphrase for the SSH key (if encrypted)

Example .env:

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

🚀 Usage

With Claude Desktop / Gemini CLI / Any MCP Client

Add the server to your MCP client configuration:

{
  "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"
      }
    }
  }
}

Development Mode

pnpm dev

Production

pnpm build
pnpm start

🛠️ Tools Reference

run_command

Execute a shell command on the VPS.

Parameter	Type	Required	Default	Description
command	string	✅	—	The shell command to execute
timeout	number	❌	30000	Timeout in milliseconds
working_directory	string	❌	—	Directory to run the command in

Returns: JSON with exit_code, stdout, and stderr.

---

read_file

Read the contents of a file on the VPS via SFTP.

Parameter	Type	Required	Default	Description
path	string	✅	—	Absolute path to the file
max_lines	number	❌	—	Max lines to return (omit for full file)

---

write_file

Write content to a file on the VPS via SFTP.

Parameter	Type	Required	Default	Description
path	string	✅	—	Absolute path to the file
content	string	✅	—	Content to write
create_dirs	boolean	❌	false	Create parent directories if missing

---

list_directory

List files and directories at a given path.

Parameter	Type	Required	Default	Description
path	string	❌	/	Directory path to list
show_hidden	boolean	❌	false	Include dotfiles
long_format	boolean	❌	true	Show permissions, size, date

---

manage_service

Manage systemd services.

| Parameter | Type | Required | Default | Description | |---------

... View full README on GitHub