Skip to main content
Glama
harbouli

vps-mcp-server

by harbouli
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

🖥️ 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

Related MCP server: MCP VPS Manager

📦 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

This server cannot be installed

F
license - not found
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/harbouli/vps-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server