mcp-ssh-vps 0.3.0

MCP server for managing VPS via SSH - gives AI agents secure access to remote servers

🔐 SSH MCP Server

Give AI agents secure access to your VPS servers via SSH
Execute commands, transfer files, manage processes — all through Model Context Protocol

Quick Start • Features • IDE Integration • Tools • Security

---

🚀 Quick Start

Install

# Via pip
pip install mcp-ssh-vps

# Via uvx (recommended for MCP)
uvx mcp-ssh-vps

Add Your First Server

# Interactive setup
uvx mcp-ssh-vps --help

# Or use the CLI
sshmcp-cli server add --name prod --host 192.168.1.100 --user deploy
sshmcp-cli server test prod

Connect to Your AI Agent

Add to your AI IDE config and start managing servers with natural language!

"Deploy my app to the production server"
"Check disk space on all servers"
"Restart nginx on web1 and web2"

---

✨ Features

Feature	Description
🖥️ Execute Commands	Run any shell command on remote servers
📁 File Operations	Read, write, and list files via SFTP
⚙️ Process Management	Control systemd, pm2, supervisor services
🏷️ Server Tags	Group servers with tags for batch operations
🔄 Batch Execution	Run commands on multiple servers in parallel
🔒 Security Profiles	Strict, moderate, or full access levels
📝 Audit Logging	Track all operations for compliance
🔑 SSH Keys & Passwords	Support for both authentication methods

---

🔌 IDE Integration

Claude Code

claude mcp add ssh-vps -s user -e SSHMCP_CONFIG_PATH=~/.sshmcp/machines.json -- uvx mcp-ssh-vps

Or add to ~/.claude.json:

{
  "mcpServers": {
    "ssh-vps": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-ssh-vps"],
      "env": {
        "SSHMCP_CONFIG_PATH": "~/.sshmcp/machines.json"
      }
    }
  }
}

---

Factory Droid

droid mcp add ssh-vps "uvx mcp-ssh-vps" --env SSHMCP_CONFIG_PATH=~/.sshmcp/machines.json

Or add to ~/.factory/mcp.json:

{
  "mcpServers": {
    "ssh-vps": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-ssh-vps"],
      "env": {
        "SSHMCP_CONFIG_PATH": "~/.sshmcp/machines.json"
      }
    }
  }
}

---

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ssh-vps": {
      "command": "uvx",
      "args": ["mcp-ssh-vps"],
      "env": {
        "SSHMCP_CONFIG_PATH": "~/.sshmcp/machines.json"
      }
    }
  }
}

---

Qwen Code

qwen mcp add ssh-vps -s user -e SSHMCP_CONFIG_PATH=~/.sshmcp/machines.json uvx mcp-ssh-vps

Or add to ~/.qwen/settings.json:

{
  "mcpServers": {
    "ssh-vps": {
      "command": "uvx",
      "args": ["mcp-ssh-vps"],
      "env": {
        "SSHMCP_CONFIG_PATH": "~/.sshmcp/machines.json"
      }
    }
  }
}

---

Claude Desktop

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ssh-vps": {
      "command": "uvx",
      "args": ["mcp-ssh-vps"],
      "env": {
        "SSHMCP_CONFIG_PATH": "~/.sshmcp/machines.json"
      }
    }
  }
}

---

VS Code + Continue

Add to .continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["mcp-ssh-vps"],
          "env": {
            "SSHMCP_CONFIG_PATH": "~/.sshmcp/machines.json"
          }
        }
      }
    ]
  }
}

---

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ssh-vps": {
      "command": "uvx",
      "args": ["mcp-ssh-vps"],
      "env": {
        "SSHMCP_CONFIG_PATH": "~/.sshmcp/machines.json"
      }
    }
  }
}

---

OpenAI Codex CLI

codex --mcp-config '{"ssh-vps": {"command": "uvx", "args": ["mcp-ssh-vps"], "env": {"SSHMCP_CONFIG_PATH": "~/.sshmcp/machines.json"}}}'

---

Any MCP-Compatible Client

Generic stdio configuration:

{
  "command": "uvx",
  "args": ["mcp-ssh-vps"],
  "env": {
    "SSHMCP_CONFIG_PATH": "/path/to/machines.json"
  }
}

---

🛠️ Tools Reference

Command Execution

Tool	Description	Example
execute_command	Run command on server	execute_command("prod", "docker ps")
execute_on_multiple	Run on multiple servers	execute_on_multiple(["*"], "uptime")

Server Management

Tool	Description	Example
list_servers	List all servers	list_servers() or list_servers(tag="web")
add_server	Add new server	add_server("web1", "1.2.3.4", "root")
remove_server	Remove server	remove_server("old-server")
test_connection	Test SSH connection	test_connection("prod")

File Operations

Tool	Description	Example
read_file	Read remote file	read_file("prod", "/var/log/app.log")
upload_file	Upload file	upload_file("prod", "/tmp/script.sh", "#!/bin/bash\n...")
list_files	List directory	list_files("prod", "/var/log")

Process Management

Tool	Description	Example
manage_process	Control services	manage_process("prod", "restart", "nginx")

Help & Info

Tool	Description	Example
get_help	Get documentation	get_help("examples")
get_allowed_commands	View security config	get_allowed_commands("prod")
get_server_info	Server details	get_server_info("prod")

---

🏷️ Server Tags & Batch Operations

Add servers with tags

add_server("web1", "192.168.1.10", "deploy", tags=["production", "web"])
add_server("web2", "192.168.1.11", "deploy", tags=["production", "web"])
add_server("db1", "192.168.1.20", "deploy", tags=["production", "database"])

Filter by tag

list_servers(tag="web")           # Only web servers
list_servers(tag="production")    # All production servers

Execute on tagged servers

execute_on_multiple(["tag:web"], "nginx -t")           # All web servers
execute_on_multiple(["tag:production"], "uptime")      # All production
execute_on_multiple(["*"], "df -h")                    # ALL servers

---

🔒 Security

Security Profiles

Profile	Allowed Commands	Use Case
strict	git, ls, cat, df, uptime	Read-only monitoring
moderate	+ docker, npm, systemctl, pm2	Standard DevOps
full	All commands (except rm -rf /)	Full access

Set security level

add_server("prod", "1.2.3.4", "root", security_level="full")

Audit Logging

All commands are logged with timestamps, user, and results:

2024-01-15T10:30:00Z | prod | root | docker ps | exit_code=0 | 150ms

---

📁 Configuration

Config Location

~/.sshmcp/machines.json

Example Config

{
  "machines": [
    {
      "name": "production",
      "host": "192.168.1.100",
      "port": 22,
      "user": "deploy",
      "auth": {
        "type": "key",
        "key_path": "~/.ssh/id_rsa"
      },
      "security": {
        "allowed_commands": [".*"],
        "forbidden_commands": [".*rm\\s+-rf\\s+/$"],
        "timeout_seconds": 120
      },
      "tags": ["production", "web"],
      "description": "Main production server"
    }
  ]
}

Environment Variable

export SSHMCP_CONFIG_PATH=/custom/path/machines.json

---

📖 Usage Examples

Check status of all servers

User: Check the status of all my servers
AI: I'll run uptime on all configured servers...

execute_on_multiple(["*"], "uptime && df -h | head -5")

Deploy application

User: Deploy the latest code to production
AI: I'll pull the latest changes and restart the service...

execute_command("prod", "cd /app && git pull origin main")
execute_command("prod", "npm install --production")
execute_command("prod", "pm2 restart all")

Debug server issues

User: Why is the web server slow?
AI: Let me check system resources and logs...

execute_command("web1", "top -bn1 | head -20")
execute_command("web1", "tail -50 /var/log/nginx/error.log")
execute_command("web1", "free -m && df -h")

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

git clone https://github.com/LuxVTZ/sshmcp.git
cd sshmcp
pip install -e ".[dev]"
pytest

---

📄 License

MIT License - see LICENSE for details.

---

Made with ❤️ for the AI agent ecosystem
PyPI • GitHub • Issues