MCP SSH Server

Fornece acesso SSH a servidores remotos, permitindo que ferramentas de IA se conectem de forma segura ao seu VPS para gerenciamento.

GitHub
50
Experimente este MCPPatrocinado

Documentação

MCP SSH Server

Um servidor Model Context Protocol (MCP) que fornece acesso abrangente a SSH e console serial para servidores remotos e dispositivos de rede. Permite que ferramentas de IA como o Claude Desktop gerenciem com segurança servidores Linux, switches de rede e dispositivos de infraestrutura por meio de conexões SSH de rede e acesso direto ao console USB-para-Serial.

Recursos

Capacidades principais de SSH

  • Gerenciamento de conexões SSH com autenticação por senha ou chave
  • Execução remota de comandos com tratamento de timeout
  • Upload e download de arquivos via SFTP
  • Listagem de diretórios e operações de arquivos
  • Tratamento seguro de conexões

Gerenciamento de dispositivos de rede

  • Acesso ao console USB-para-Serial - Conexões diretas de console via adaptadores FTDI e outros adaptadores USB
  • Gerenciamento de switches de rede - Suporte completo para switches Cisco IOS/IOS-XE e Aruba
  • Descoberta de dispositivos - Detecção automática de tipos e capacidades de switches
  • Gerenciamento de configuração - Backup, restauração e configuração automatizada
  • Diagnósticos de rede - Ping, traceroute e testes de conectividade integrados
  • Transição de console para SSH - Configuração automatizada de SSH via conexão de console
  • Gerenciamento de firmware - Upload, verificação, instalação e rollback de firmware de switches

Gerenciamento de servidores

  • Ferramentas de gerenciamento de servidores Ubuntu (Nginx, SSL, pacotes, firewall)
  • Compatível com Claude Desktop, VS Code e outros clientes compatíveis com MCP

Testes de produção no mundo real

Esta ferramenta foi amplamente testada em ambientes de rede de produção:

  • Descoberta de rede - Descobriu com sucesso portas anteriormente desconhecidas em switches de produção que estavam causando problemas intermitentes de conectividade
  • Zero downtime - Gerenciou vários switches em redes de produção ativas sem causar interrupções ou quedas de rede
  • Economia de tempo - A configuração automatizada de SSH reduziu o tempo de configuração de switches de 15-20 minutos para menos de 2 minutos
  • Confiabilidade - Zero incidentes durante implantações de produção em vários dispositivos de rede
  • Compatibilidade USB-para-Serial - Testado com adaptadores FTDI FT232R/FT232H, Prolific PL2303, Silicon Labs CP2102/CP2104 e CH340
  • Compatibilidade com switches - Validado em switches Cisco Catalyst 2960/3560/3750 e Aruba 2530/2930

A ferramenta provou ser confiável o suficiente para tarefas de gerenciamento de rede em produção, sem exigir um ambiente de laboratório separado para testes.

Pré-requisitos

  • Node.js 18 ou superior
  • npm ou yarn
  • Compatível com Windows, macOS e Linux

Instalação

  1. Clone o repositório:

    git clone https://github.com/yourusername/mcp-ssh-server.git
cd mcp-ssh-server

  2. Instale as dependências:

    npm install

  3. Compile o projeto:

    npm run build

  4. Instale globalmente (opcional):

    npm install -g .

Configuração

Configuração do Claude Desktop

  1. Abra o Claude Desktop
  2. Vá em Configurações > Desenvolvedor (ou pressione Ctrl+Shift+D)
  3. Edite a configuração do MCP
  4. Adicione a seguinte configuração:
{
  "mcpServers": {
    "ssh-server": {
      "command": "node",
      "args": ["/path/to/mcp-ssh-server/build/index.js"],
      "env": {
        "NODE_NO_WARNINGS": "1"
      }
    }
  }
}

Importante: Substitua /path/to/mcp-ssh-server/build/index.js pelo caminho absoluto para o seu arquivo index.js compilado.

Configuração do VS Code (se estiver usando a extensão MCP)

Crie ou edite .vscode/mcp.json no seu workspace:

{
  "mcpServers": {
    "ssh-server": {
      "command": "node",
      "args": ["/path/to/mcp-ssh-server/build/index.js"]
    }
  }
}

Ferramentas disponíveis

Ferramentas principais de SSH

ssh_connect

Estabelece uma conexão SSH com um servidor remoto.

Parâmetros:

  • host (obrigatório) - Nome do host ou endereço IP
  • username (obrigatório) - Nome de usuário SSH
  • password (opcional) - Senha SSH
  • privateKeyPath (opcional) - Caminho para o arquivo de chave privada
  • passphrase (opcional) - Frase secreta da chave privada
  • port (opcional) - Porta SSH (padrão: 22)
  • connectionId (opcional) - Identificador exclusivo para esta conexão

Retorna:

  • success - Booleano indicando sucesso
  • connectionId - ID a ser usado para comandos subsequentes
  • message - Mensagem de status da conexão

Exemplo:

Connect to my server at example.com using username 'admin' and password authentication

ssh_exec

Executa um comando no servidor remoto.

Parâmetros:

  • connectionId (obrigatório) - ID do ssh_connect
  • command (obrigatório) - Comando a ser executado
  • cwd (opcional) - Diretório de trabalho
  • timeout (opcional) - Timeout do comando em milissegundos (padrão: 60000)

Retorna:

  • code - Código de saída
  • signal - Sinal que terminou o processo (se houver)
  • stdout - Saída padrão
  • stderr - Erro padrão

Exemplo:

Run "ls -la /var/www/html" on the server

ssh_upload_file

Envia um arquivo para o servidor remoto.

Parâmetros:

  • connectionId (obrigatório) - ID do ssh_connect
  • localPath (obrigatório) - Caminho do arquivo local
  • remotePath (obrigatório) - Caminho de destino remoto

Retorna:

  • success - Booleano indicando sucesso
  • message - Mensagem de status do upload

ssh_download_file

Baixa um arquivo do servidor remoto.

Parâmetros:

  • connectionId (obrigatório) - ID do ssh_connect
  • remotePath (obrigatório) - Caminho do arquivo remoto
  • localPath (obrigatório) - Caminho de destino local

Retorna:

  • success - Booleano indicando sucesso
  • message - Mensagem de status do download

ssh_list_files

Lista arquivos em um diretório no servidor remoto.

Parâmetros:

  • connectionId (obrigatório) - ID do ssh_connect
  • remotePath (obrigatório) - Caminho do diretório a ser listado

Retorna:

  • files - Matriz de objetos de arquivo com propriedades:
    • filename - Nome do arquivo
    • isDirectory - Booleano indicando se é um diretório
    • size - Tamanho do arquivo
    • lastModified - Horário da última modificação

ssh_disconnect

Fecha uma conexão SSH.

Parâmetros:

  • connectionId (obrigatório) - ID do ssh_connect

Retorna:

  • success - Booleano indicando sucesso
  • message - Mensagem de status da desconexão

Exemplos de uso com o Claude

  1. Conecte-se ao seu servidor:

    Please connect to my VPS at example.com using username 'admin' and my SSH key at ~/.ssh/id_rsa

  2. Verifique o status do servidor:

    Run the command "systemctl status nginx" to check web server status

  3. Envie um arquivo do site:

    Upload my local file ~/websites/index.html to /var/www/html/index.html on the server

  4. Liste os arquivos do site:

    Show me all files in the /var/www/html directory

  5. Baixe um backup:

    Download the file /var/backups/website-backup.tar.gz to my local Downloads folder

  6. Desconecte quando terminar:

    Please disconnect from the SSH session

Ferramentas de gerenciamento de switches de rede

switch_discover_device

Descobre e identifica o tipo de dispositivo e as capacidades do switch de rede.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • enablePassword (opcional) - Senha de enable para o modo privilegiado

switch_show_interfaces

Mostra o status das interfaces e a configuração no switch de rede.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • interfaceType (opcional) - Tipo de interfaces a mostrar
  • enablePassword (opcional) - Senha de enable para o modo privilegiado

switch_show_vlans

Mostra a configuração e o status das VLANs no switch de rede.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • enablePassword (opcional) - Senha de enable para o modo privilegiado

switch_backup_config

Faz backup da configuração do switch (configuração ativa ou de inicialização).

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • configType (opcional) - Tipo de configuração para backup
  • enablePassword (opcional) - Senha de enable para o modo privilegiado

switch_network_diagnostics

Executa diagnósticos de rede a partir do switch (ping, traceroute).

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • target (obrigatório) - Endereço IP ou nome de host de destino
  • diagnosticType (opcional) - Tipo de diagnóstico a executar
  • enablePassword (opcional) - Senha de enable para o modo privilegiado

switch_show_mac_table

Mostra a tabela de endereços MAC no switch de rede.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • vlan (opcional) - VLAN específica para mostrar endereços MAC
  • enablePassword (opcional) - Senha de enable para o modo privilegiado

Ferramentas de console USB-para-Serial

Essas ferramentas permitem acesso direto ao console de dispositivos de rede usando adaptadores USB-para-Serial. Isso é essencial para a configuração inicial do dispositivo, acesso de emergência quando a conectividade de rede é perdida ou quando o SSH ainda não foi configurado.

Adaptadores USB-para-Serial suportados:

  • FTDI FT232R/FT232H (recomendado - mais confiável)
  • Prolific PL2303 (amplamente compatível)
  • Silicon Labs CP2102/CP2104 (bom desempenho)
  • Chipsets CH340/CH341 (opção econômica)

Todos os adaptadores funcionam com cabos de console padrão Cisco/Aruba (RJ45 para DB9 ou USB direto).

serial_list_ports

Lista as portas USB-para-Serial disponíveis no sistema. Detecta automaticamente adaptadores FTDI, Prolific, Silicon Labs e CH340.

Exemplo:

Show me all available serial ports

serial_connect

Conecta a um dispositivo de rede via porta de console USB-para-Serial.

Parâmetros:

  • port (obrigatório) - Nome da porta serial (ex.: COM3 no Windows, /dev/ttyUSB0 no Linux)
  • baudRate (opcional) - Taxa de transmissão (padrão: 9600 para a maioria dos switches)
  • connectionId (opcional) - Identificador exclusivo para a conexão
  • deviceType (opcional) - Tipo de dispositivo para configurações ideais (cisco, aruba, generic)

Exemplo:

Connect to my Cisco switch console on COM3

serial_send_command

Envia um comando para o dispositivo de rede via conexão serial.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão serial ativa
  • command (obrigatório) - Comando a ser enviado ao dispositivo
  • waitForResponse (opcional) - Aguardar resposta do dispositivo
  • timeout (opcional) - Timeout de resposta em milissegundos

Exemplo:

Send "show version" command to the console connection

serial_discover_device

Descobre o tipo de dispositivo e capacidades via conexão serial. Identifica automaticamente dispositivos Cisco IOS, Cisco IOS-XE, Aruba e genéricos.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão serial ativa

Exemplo:

Discover what type of device is connected

serial_list_connections

Lista todas as conexões seriais ativas.

serial_disconnect

Desconecta de uma porta serial.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão serial ativa

Ferramentas de gerenciamento de sites Ubuntu

As seguintes ferramentas de gerenciamento de servidores Ubuntu estão disponíveis:

  • ubuntu_nginx_control - Controle do servidor web (start, stop, restart, status, reload, check-config)
  • ubuntu_update_packages - Atualizações de pacotes do sistema com opção somente de segurança
  • ubuntu_ssl_certificate - Gerenciamento de certificados SSL usando Let's Encrypt (issue, renew, status, list)
  • ubuntu_website_deployment - Implantação de sites com backup e restauração automáticos
  • ubuntu_ufw_firewall - Gerenciamento de firewall (UFW) (enable, disable, allow, deny, delete)

Ferramentas de configuração e automação SSH

Essas ferramentas automatizam o processo de configurar o acesso SSH em switches de rede via conexão de console, permitindo uma transição suave do gerenciamento somente por console para o baseado em SSH.

switch_generate_ssh_config

Gera um modelo de configuração SSH para um switch de rede com base no tipo de dispositivo e no nível de segurança.

Parâmetros:

  • deviceType (opcional) - Tipo de dispositivo: cisco, aruba (detectado automaticamente se não especificado)
  • securityLevel (opcional) - Nível de segurança: basic, secure (padrão: basic)
  • hostname (obrigatório) - Nome do host do switch
  • ip_address (obrigatório) - Endereço IP de gerenciamento
  • subnet_mask (opcional) - Máscara de sub-rede (padrão: 255.255.255.0)
  • gateway (obrigatório) - Gateway padrão
  • username (obrigatório) - Nome de usuário SSH
  • password (obrigatório) - Senha SSH

switch_apply_ssh_config

Aplica a configuração SSH a um switch via uma conexão serial de console ativa.

Parâmetros:

  • serialConnectionId (obrigatório) - ID de uma conexão serial ativa
  • deviceType (opcional) - Tipo de dispositivo: cisco, aruba
  • hostname (obrigatório) - Nome do host do switch
  • ip_address (obrigatório) - Endereço IP de gerenciamento
  • gateway (obrigatório) - Gateway padrão
  • username (obrigatório) - Nome de usuário SSH
  • password (obrigatório) - Senha SSH
  • confirmApply (obrigatório) - Deve ser true para prosseguir

switch_verify_ssh_status

Verifica o status atual da configuração SSH em um switch via conexão serial.

Parâmetros:

  • serialConnectionId (obrigatório) - ID de uma conexão serial ativa

switch_test_ssh_connection

Teste a conectividade SSH com um switch recém-configurado.

Parâmetros:

  • ip_address (obrigatório) - Endereço IP do switch
  • username (obrigatório) - Nome de usuário SSH
  • password (obrigatório) - Senha SSH
  • port (opcional) - Porta SSH (padrão: 22)

switch_complete_ssh_setup

Fluxo de trabalho completo de configuração SSH de ponta a ponta via conexão de console. Isso automatiza todo o processo de configuração de SSH em um switch.

Parâmetros:

  • serialConnectionId (obrigatório) - ID de uma conexão serial ativa
  • hostname (obrigatório) - Nome do host do switch
  • ip_address (obrigatório) - Endereço IP de gerenciamento
  • gateway (obrigatório) - Gateway padrão
  • username (obrigatório) - Nome de usuário SSH
  • password (obrigatório) - Senha SSH
  • confirmSetup (obrigatório) - Deve ser verdadeiro para prosseguir

Ferramentas de Transição de Console para SSH

console_to_ssh_transition

Fluxo de trabalho automatizado completo para transicionar um switch de rede de acesso somente via console para gerenciamento via SSH. Esta é a ferramenta recomendada para a configuração inicial do switch.

Parâmetros:

  • port (obrigatório) - Porta serial (por exemplo, COM3, /dev/ttyUSB0)
  • hostname (obrigatório) - Nome do host do switch
  • ip_address (obrigatório) - Endereço IP de gerenciamento
  • gateway (obrigatório) - Gateway padrão
  • username (obrigatório) - Nome de usuário SSH
  • password (obrigatório) - Senha SSH
  • deviceType (opcional) - Tipo de dispositivo: cisco, aruba (detectado automaticamente se não especificado)
  • confirmTransition (obrigatório) - Deve ser verdadeiro para prosseguir

Exemplo:

Set up SSH on my Cisco switch connected to COM3 with hostname "switch-core-01", IP 192.168.1.10, gateway 192.168.1.1, username "admin"

quick_ssh_check

Verificação rápida do status SSH em um switch por meio de conexão serial sem fazer alterações.

Parâmetros:

  • port (obrigatório) - Porta serial
  • baudRate (opcional) - Taxa de transmissão (padrão: 9600)
  • enablePassword (opcional) - Senha de habilitação, se necessário

Ferramentas de Gerenciamento de Firmware

Essas ferramentas fornecem recursos abrangentes de gerenciamento de firmware para switches de rede, incluindo verificação de versão, upload de firmware, verificação, instalação e preparação para rollback.

switch_check_firmware

Verificar a versão atual do firmware e as informações do sistema em um switch de rede.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • enablePassword (opcional) - Senha de habilitação para o modo privilegiado

Retornos:

  • Versão atual do firmware
  • Versão de inicialização (boot)
  • Modelo do dispositivo e número de série
  • Tempo de atividade do sistema
  • Saída completa da versão

switch_check_storage

Verificar o espaço de armazenamento disponível no switch antes do upload do firmware.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • enablePassword (opcional) - Senha de habilitação para o modo privilegiado

Retornos:

  • Informações de armazenamento flash
  • Espaço disponível
  • Detalhes do sistema de arquivos

switch_upload_firmware

Enviar um arquivo de firmware para o switch de rede via SFTP. Suporta arquivos grandes com tempo limite de 30 minutos.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • localFirmwarePath (obrigatório) - Caminho local para o arquivo de firmware
  • remotePath (opcional) - Caminho remoto no switch (padrão: flash:/nome_do_arquivo)
  • enablePassword (opcional) - Senha de habilitação para o modo privilegiado

Exemplo:

Upload firmware file ~/downloads/c2960-lanbasek9-mz.150-2.SE11.bin to the switch

switch_verify_firmware

Verificar a integridade do arquivo de firmware enviado no switch usando somas de verificação MD5.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • firmwarePath (obrigatório) - Caminho para o arquivo de firmware no switch
  • enablePassword (opcional) - Senha de habilitação para o modo privilegiado

Retornos:

  • Status da verificação
  • Resultados da soma de verificação MD5
  • Informações do arquivo

switch_install_firmware

Instalar firmware no switch e reiniciar opcionalmente para aplicar a atualização.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • firmwarePath (obrigatório) - Caminho para o arquivo de firmware no switch
  • enablePassword (opcional) - Senha de habilitação para o modo privilegiado
  • autoReboot (opcional) - Reiniciar automaticamente após a instalação (padrão: falso)

Importante: Isso modifica a configuração de inicialização. Teste em um ambiente de laboratório primeiro!

Exemplo:

Install firmware flash:/c2960-lanbasek9-mz.150-2.SE11.bin and reboot the switch

switch_prepare_rollback

Preparar informações necessárias para o rollback de firmware em caso de problemas com o novo firmware.

Parâmetros:

  • connectionId (obrigatório) - ID de uma conexão SSH ativa
  • enablePassword (opcional) - Senha de habilitação para o modo privilegiado

Retornos:

  • Configuração de inicialização atual
  • Imagens de firmware disponíveis
  • Instruções de rollback

Configuração de Console USB para Serial

Requisitos de Hardware

Adaptadores USB para Serial:

  • Adaptadores baseados em FTDI (FT232R, FT232H) - Melhor escolha para confiabilidade
  • Prolific PL2303 - Amplamente disponível e compatível
  • Silicon Labs CP2102/CP2104 - Bom desempenho e estabilidade
  • CH340/CH341 - Opção econômica, funciona bem na maioria dos sistemas

Cabos de Console:

  • Cabo de console Cisco (RJ45 para DB9 ou USB)
  • Cabo de console Aruba/HP (RJ45 para DB9 ou USB)
  • Cabos de console universais funcionam com a maioria dos dispositivos

Instalação dos Drivers

Windows:

  • Drivers FTDI: Normalmente instalados automaticamente, ou baixe em ftdichip.com
  • Drivers Prolific: Disponíveis em prolific.com.tw
  • Drivers Silicon Labs: Baixe em silabs.com
  • Drivers CH340: Normalmente incluídos no Windows 10/11, ou baixados separadamente

macOS:

  • Adaptadores FTDI: Normalmente funcionam sem configuração adicional
  • Outros adaptadores: Podem exigir instalação de driver do fabricante

Linux:

  • A maioria dos adaptadores funciona imediatamente com os drivers do kernel
  • FTDI, Silicon Labs, CH340: Integrados ao kernel
  • Verifique dmesg após conectar o adaptador para confirmar a detecção

Início Rápido com Console

  1. Conecte o adaptador USB para Serial ao computador
  2. Conecte o cabo de console do adaptador à porta de console do switch
  3. Liste as portas disponíveis: "Mostre-me as portas seriais disponíveis"
  4. Conecte à porta: "Conecte a COM3 para switch Cisco"
  5. Envie comandos ou execute a configuração automatizada

Notas de Segurança

  • Armazene chaves privadas SSH com segurança
  • Use autenticação baseada em chave quando possível
  • Limite o acesso SSH a endereços IP específicos
  • Mantenha seu servidor atualizado
  • Use senhas ou frases secretas fortes (mínimo de 8 caracteres)
  • Proteja o acesso físico às portas de console e aos adaptadores USB para Serial
  • Considere definir variáveis de ambiente em um arquivo .env para informações sensíveis

Solução de Problemas

O servidor não inicia

  • Verifique se o Node.js está instalado: node --version
  • Verifique se todas as dependências estão instaladas: npm install
  • Recompile o projeto: npm run build

Problemas de conexão

  • Verifique se o servidor SSH está em execução no destino
  • Verifique as configurações do firewall
  • Confirme se as credenciais estão corretas
  • Teste a conexão SSH manualmente primeiro

Integração com Claude Desktop

  • Garanta que o caminho na configuração seja absoluto
  • Reinicie o Claude Desktop após alterações na configuração
  • Verifique o Console do Desenvolvedor para mensagens de erro

Desenvolvimento

Para modificar ou estender o servidor:

  1. Edite os arquivos de origem em src/
  2. Recompile: npm run build
  3. Teste suas alterações
  4. Reinicie o Claude Desktop ou o VS Code para aplicar as alterações

Executando em Modo de Desenvolvimento

Para testes rápidos durante o desenvolvimento:

npm run dev

Contribuição

Contribuições para ferramentas e recursos adicionais são bem-vindas. Sinta-se à vontade para enviar pull requests ou abrir issues para melhorias e correções de bugs.

Licença

Licença MIT