vps-ops-mcp

Servidor MCP (stdio) que opera uma VPS por SSH. O Cursor e o Codex sobem o processo com bun e chamam ferramentas de leitura (saúde do host, debug Unix, Docker, Compose, Swarm, firewall) e de mutação (restart, stop, start, prune), com confirmação explícita nas mutações.

O transporte é stdio. Não abra o servidor como um processo longo na mão: o cliente (Cursor ou Codex) é quem o inicia.

Contribuição

Veja CONTRIBUTING.md (branches, pull requests, verificação) e ISSUE.md (como abrir uma issue).

Related MCP server: Secure VPS Operations MCP Server

Requisitos

• Bun

• Python 3 (usado pelos scripts de registro)

• Cliente OpenSSH (ssh no PATH)

• Chave privada SSH legível, com acesso ao usuário remoto

• No host remoto: Docker (e sudo -n para ufw, fail2ban, sshd -T, ss e dmesg, se for usar essas ferramentas)

Configuração

cp .env.example .env

Edite .env. O arquivo está no .gitignore.

VPS_COMPOSE_DIR precisa ser absoluto e casar com /^[a-zA-Z0-9/_.-]+$/ (começa com /).

Instalação

bun install

Registrar nos clientes

Os scripts gravam a configuração do MCP com as variáveis já exportadas no shell. Eles não leem .env sozinhos. Sem exportar, entram os padrões do script (host, usuário, porta e um caminho de chave local).

Faça isto uma vez, na raiz do repositório, antes de cada script:

set -a
source .env
set +a

Cada execução faz backup do arquivo de destino (*.bak.YYYYMMDDHHMMSS) e substitui só o servidor vps-ops. Os outros servidores MCP permanecem.

Variáveis opcionais dos scripts:

VPS_COMPOSE_DIR só entra na config do cliente se estiver definida e não vazia.

Cursor

Registro global (vale em qualquer workspace):

./scripts/register-cursor-mcp.sh

O script escreve em ~/.cursor/mcp.json, no formato:

{
  "mcpServers": {
    "vps-ops": {
      "command": "bun",
      "args": ["/caminho/absoluto/vps-ops-mcp/src/index.ts"],
      "env": {
        "VPS_HOST": "seu.host",
        "VPS_USER": "ubuntu",
        "VPS_PORT": "22",
        "VPS_SSH_KEY_PATH": "/caminho/absoluto/chave",
        "VPS_COMMAND_TIMEOUT_MS": "30000",
        "VPS_LOG_MAX_BYTES": "200000",
        "VPS_ALLOW_MUTATIONS": "true"
      }
    }
  }
}

Para limitar a um projeto, aponte o script para o mcp.json desse projeto:

CURSOR_MCP_JSON="/caminho/do/projeto/.cursor/mcp.json" ./scripts/register-cursor-mcp.sh

Depois: recarregue a janela do Cursor (Command Palette → Developer: Reload Window) ou reinicie o servidor em Settings → MCP. O servidor aparece como vps-ops.

Codex

./scripts/register-codex-mcp.sh

O script escreve em ~/.codex/config.toml:

[mcp_servers.vps-ops]
command = "bun"
args = ["/caminho/absoluto/vps-ops-mcp/src/index.ts"]

[mcp_servers.vps-ops.env]
VPS_HOST = "seu.host"
VPS_USER = "ubuntu"
VPS_PORT = "22"
VPS_SSH_KEY_PATH = "/caminho/absoluto/chave"
VPS_COMMAND_TIMEOUT_MS = "30000"
VPS_LOG_MAX_BYTES = "200000"
VPS_ALLOW_MUTATIONS = "true"

Feche e abra a sessão do Codex para ele reler o config.toml. Se o CLI estiver no PATH, codex mcp list deve mostrar vps-ops.

Verificar

Teste o SSH fora do MCP (os mesmos flags que o servidor usa):

ssh -i "$VPS_SSH_KEY_PATH" \
  -o BatchMode=yes \
  -o IdentitiesOnly=yes \
  -o StrictHostKeyChecking=accept-new \
  -p "${VPS_PORT:-22}" \
  "${VPS_USER}@${VPS_HOST}" \
  'uname -a'

No Cursor ou no Codex, peça para chamar vps_ping. A resposta é JSON:

{
  "exit_code": 0,
  "stdout": "...",
  "stderr": "",
  "duration_ms": 0,
  "truncated": false
}

exit_code diferente de 0 marca a chamada como erro no MCP. Se o processo sair na hora com VPS_SSH_KEY_PATH is required ou missing or unreadable, a variável não chegou no env do cliente — rode o script de registro de novo com o .env exportado.

Ferramentas

Toda chamada devolve exit_code, stdout, stderr, duration_ms e truncated.

Leitura

Nomes de container, serviço, imagem e jail precisam casar com ^[a-zA-Z0-9][a-zA-Z0-9_.-]*$.

Mutação

Exigem confirm: true. Com VPS_ALLOW_MUTATIONS=false, todas são recusadas.

Segurança

• Comandos remotos são fixos. Não existe ferramenta de shell livre.

• Argumentos de nome e caminho passam por allowlist e são citados no shell.

• SSH usa BatchMode=yes, IdentitiesOnly=yes e StrictHostKeyChecking=accept-new.

• Mutação sem confirm: true é recusada. docker_rm pede o nome duas vezes. Prune de volumes pede confirm_volumes: true.

• Para um cliente só de leitura, registre com VPS_ALLOW_MUTATIONS=false.