🖥️ 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
service	string	✅	—	Service name (e.g., nginx)
action	enum	✅	—	start | stop | restart | reload | status | enable | disable | logs
log_lines	number	❌	50	Lines to show (for logs action)

---

list_services

List systemd services filtered by state.

Parameter	Type	Required	Default	Description
filter	enum	❌	running	all | running | failed | enabled

---

system_stats

Get system resource usage.

Parameter	Type	Required	Default	Description
include	array	❌	["all"]	cpu | memory | disk | network | uptime | processes | all

---

docker

Manage Docker containers.

Parameter	Type	Required	Default	Description
action	enum	✅	—	ps | start | stop | restart | logs | stats | images
container	string	❌	—	Container name/ID (required for start/stop/restart/logs)
log_lines	number	❌	50	Lines to show (for logs action)

---

firewall

Manage UFW firewall rules.

Parameter	Type	Required	Default	Description
action	enum	✅	—	status | allow | deny | delete | reset
rule	string	❌	—	Rule spec (e.g., 80/tcp, 443, from 10.0.0.1)

📁 Project Structure

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

🔒 Security Notes

• The server connects via SSH using key-based authentication (no passwords).
• Commands run with the privileges of the configured SSH user.
• Service management and firewall tools use sudo — ensure your SSH user has appropriate sudoers permissions.
• The server maintains a persistent SSH connection that is automatically reconnected if dropped.

📄 License

MIT