netdev-ssh-mcp

Servidor MCP para interagir com dispositivos de rede (switches, roteadores) via SSH. Suporta Arista EOS, Cisco NX-OS e Cisco IOS/IOS-XE. Expõe operações de dispositivos de rede como ferramentas para uso com Claude Code e Claude Desktop (e outros clientes MCP)

GitHub

Experimente este MCPPatrocinado

Documentação

netdev-ssh-mcp

Servidor MCP para interagir com dispositivos de rede (switches, roteadores, firewalls) via SSH. Suporta Arista EOS, Cisco NX-OS, Cisco IOS/IOS-XE, Juniper JunOS e FortiGate FortiOS. Expõe operações de dispositivos de rede como ferramentas para uso com Claude Code / Claude Desktop / Codex (e outros clientes MCP)

Ferramentas

`get_config`

Recupera a configuração ativa (running) ou de inicialização (startup) de um dispositivo Arista, Cisco Nexus, Cisco Catalyst, Juniper JunOS ou FortiGate FortiOS. Valores sensíveis (senhas, segredos, nomes de comunidades SNMP, chaves BGP/OSPF/TACACS/RADIUS/IKE) são automaticamente substituídos por hashes SHA-256 determinísticos:

enable secret [h:a3f4b2c1d5e6]
snmp-server community [h:f9e1d2b4c3a7] ro
username admin privilege 15 secret [h:a3f4b2c1d5e6]

O mesmo valor secreto sempre produz o mesmo hash, portanto configurações de diferentes dispositivos podem ser comparadas e comparadas com segurança — hashes idênticos significam segredos idênticos.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`host`	string	sim	—	Nome do host ou endereço IP do dispositivo
`username`	string	não	`DEVICE_USERNAME`	Nome de usuário SSH
`port`	int	não	22	Porta SSH
`config_type`	string	não	`running`	`running` ou `startup`; `startup` não é suportado em JunOS ou FortiOS
`device_type`	string	não	—	`eos`, `ios`, `nxos`, `junos` ou `fortios`

Notas sobre FortiOS:

Use device_type=fortios para recuperar a configuração com show full-configuration.
fortigate é aceito como um alias para fortios.
FortiOS não suporta config_type=startup.

`run_show_command`

Executa comandos operacionais de leitura em um dispositivo de rede e retorna a saída. Para Arista/Cisco/JunOS, o comando deve começar com show. Para FortiOS, o comando deve começar com get. Anexe | json para saída estruturada onde suportado, ou | no-more para desabilitar a paginação para saída de texto.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`host`	string	sim	—	Nome do host ou endereço IP do dispositivo
`command`	string	sim	—	O comando operacional de leitura a ser executado
`username`	string	não	`DEVICE_USERNAME`	Nome de usuário SSH
`port`	int	não	22	Porta SSH
`device_type`	string	não	—	`eos`, `ios`, `nxos`, `junos` ou `fortios`

Exemplos de comandos:

show bgp summary | json
show interfaces status | json
show lldp neighbors detail | json
show inventory | json
show version | json
show ip route | json
get system status
get router info routing-table all

show running-config e show startup-config não são permitidos aqui — use a ferramenta get_config em vez disso.

No FortiOS, os comandos show, config, execute e diagnose são bloqueados aqui. Use get_config, run_ping ou run_traceroute em vez disso.

`run_ping`

Executa um comando ping no dispositivo de rede e retorna a saída. Útil para verificar a alcançabilidade da perspectiva do dispositivo — por exemplo, testando a conectividade com um peer BGP, próximo salto ou alvo de gerenciamento.

Use device_type para selecionar a sintaxe de comando correta para a plataforma alvo. Se omitido, a sintaxe EOS/IOS é usada (palavras-chave repeat, size). No FortiOS, a ferramenta usa execute ping-options ..., executa execute ping e depois redefine as opções dentro da mesma sessão SSH.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`host`	string	sim	—	Nome do host ou endereço IP do dispositivo
`destination`	string	sim	—	Endereço IP ou nome do host para ping
`username`	string	não	`DEVICE_USERNAME`	Nome de usuário SSH
`port`	int	não	22	Porta SSH
`count`	int	não	—	Número de solicitações de eco a enviar
`timeout`	int	não	—	Tempo limite por sonda em segundos; suportado no FortiOS
`source`	string	não	—	Endereço IP de origem ou nome da interface
`vrf`	string	não	—	Nome do VRF
`size`	int	não	—	Tamanho do pacote em bytes
`outgoing_interface`	string	não	—	Interface de saída; suportado no FortiOS
`device_type`	string	não	—	`eos`, `ios`, `nxos`, `junos` ou `fortios` — controla a sintaxe do ping

Limitações do FortiOS:

vrf não é suportado nesta ferramenta para FortiOS 7.4+.
| json não é suportado para saída operacional do FortiOS.

`run_traceroute`

Mostra o caminho salto a salto do dispositivo até um destino e a latência por salto. Útil para localizar onde a conectividade se rompe, verificar se o tráfego segue o caminho esperado e identificar qual salto introduz latência.

Use device_type para garantir a sintaxe correta. No IOS, vrf deve preceder o destino no comando — especificar device_type=ios lida com isso automaticamente. No FortiOS, a ferramenta usa execute traceroute-options ..., executa execute traceroute e depois redefine as opções dentro da mesma sessão SSH.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`host`	string	sim	—	Nome do host ou endereço IP do dispositivo
`destination`	string	sim	—	Endereço IP ou nome do host para rastrear
`username`	string	não	`DEVICE_USERNAME`	Nome de usuário SSH
`port`	int	não	22	Porta SSH
`max_hops`	int	não	—	Número máximo de saltos (TTL)
`timeout`	int	não	—	Tempo limite por sonda em segundos
`probe`	int	não	—	Número de sondas por salto
`source`	string	não	—	Endereço IP de origem ou nome da interface
`vrf`	string	não	—	Nome do VRF
`outgoing_interface`	string	não	—	Interface de saída; suportado no FortiOS
`device_type`	string	não	—	`eos`, `ios`, `nxos`, `junos` ou `fortios` — controla a sintaxe do traceroute

Limitações do FortiOS:

vrf, max_hops e timeout não são suportados nesta ferramenta para FortiOS 7.4+.
| json não é suportado para saída operacional do FortiOS.

`trust_host_key`

Busca a chave de host SSH atualmente apresentada por um dispositivo e opcionalmente a adiciona ao arquivo known_hosts configurado. Use em duas etapas:

Chame com confirm=false para inspecionar a impressão digital atual.
Após verificar essa impressão digital fora de banda, chame novamente com confirm=true para gravá-la em known_hosts.

Se uma chave de host de dispositivo mudou legitimamente, chame com replace_existing=true após verificar a nova impressão digital.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`host`	string	sim	—	Nome do host ou endereço IP do dispositivo
`port`	int	não	22	Porta SSH
`confirm`	bool	não	`false`	Quando `false`, apenas inspeciona a chave atual; quando `true`, grava-a
`replace_existing`	bool	não	`false`	Substitui uma chave existente incompatível após verificação

Nome de usuário padrão

Defina DEVICE_USERNAME para evitar especificar username em cada chamada de ferramenta:

export DEVICE_USERNAME=admin

O parâmetro da ferramenta username tem precedência se fornecido.

Autenticação

Os métodos de autenticação são tentados em ordem:

Agente SSH — se SSH_AUTH_SOCK estiver definido, o agente é usado automaticamente. Nenhuma configuração necessária.
Senha — definida via variável de ambiente DEVICE_PASSWORD (veja abaixo).

Pelo menos um método deve estar disponível no momento da chamada.

Nota sobre Claude Desktop: Claude Desktop é um aplicativo GUI e não herda o ambiente do seu shell, portanto SSH_AUTH_SOCK não está disponível para o processo do servidor MCP. Defina-o explicitamente no bloco env da configuração (veja a seção Claude Desktop abaixo). O Claude Code roda no terminal e herda o ambiente do seu shell, portanto nenhuma configuração extra é necessária lá.

Senha via variável de ambiente

Defina DEVICE_PASSWORD antes de iniciar o servidor:

export DEVICE_PASSWORD=mysecret
netdev-ssh-mcp

A senha nunca é passada por parâmetros de ferramenta ou pelo protocolo MCP — ela é lida uma vez do ambiente no momento da chamada e se aplica a todas as conexões feitas pelo processo do servidor.

Verificação de Chave de Host

A verificação de chave de host SSH está habilitada por padrão. O servidor usa o arquivo OpenSSH known_hosts do usuário atual:

macOS e Linux: ~/.ssh/known_hosts
Windows: %USERPROFILE%\\.ssh\\known_hosts

Você pode substituir o caminho com:

flag de linha de comando: --known-hosts /path/to/known_hosts
variável de ambiente: SSH_KNOWN_HOSTS

Se um dispositivo não estiver presente em known_hosts, as chamadas de ferramenta falham com um erro claro que inclui a impressão digital apresentada e sugere usar trust_host_key.

Para desabilitar completamente a verificação de chave de host, use:

flag de linha de comando: --insecure-skip-host-key-check
variável de ambiente: SKIP_HOST_KEY_CHECK=true

Desabilitar a verificação é inseguro e deve ser usado apenas como uma saída temporária.

Instalação

macOS (Homebrew)

brew install --cask krisiasty/tap/netdev-ssh-mcp

O binário é instalado em $(brew --prefix)/bin/netdev-ssh-mcp. O prefixo depende da arquitetura do Mac:

Arquitetura	Caminho
Apple Silicon (M1/M2/M3/M4)	`/opt/homebrew/bin/netdev-ssh-mcp`
Intel	`/usr/local/bin/netdev-ssh-mcp`

Execute brew --prefix para confirmar qual se aplica à sua máquina.

Compilar a partir do código-fonte

Requer Go 1.26 ou posterior.

go build -o netdev-ssh-mcp .

Para instalar o binário em /usr/local/bin após a compilação (macOS e Linux):

sudo install -m 0755 netdev-ssh-mcp /usr/local/bin/

Integração

Nos exemplos abaixo, substitua <path-to-binary> pelo caminho completo para o binário. Se instalado via Homebrew, execute brew --prefix para determinar o caminho correto (/opt/homebrew no Apple Silicon, /usr/local no Intel) e depois anexe /bin/netdev-ssh-mcp.

Claude Code

Adicione um .mcp.json local ao projeto na raiz do seu repositório:

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>"
    }
  }
}

Com um nome de usuário padrão:

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "env": {
        "DEVICE_USERNAME": "admin"
      }
    }
  }
}

O Claude Code roda no terminal e herda o ambiente do seu shell, portanto SSH_AUTH_SOCK está disponível automaticamente — nenhuma configuração extra necessária para autenticação por agente SSH.

Alternativamente, usando autenticação por senha:

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "env": {
        "DEVICE_USERNAME": "admin",
        "DEVICE_PASSWORD": "mysecret"
      }
    }
  }
}

Alternativamente, registre o servidor globalmente com a CLI do Claude Code:

claude mcp add netdev-ssh-mcp <path-to-binary>

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>"
    }
  }
}

O Claude Desktop não herda o ambiente do seu shell, portanto SSH_AUTH_SOCK deve ser definido explicitamente. Obtenha o caminho do socket atual do seu terminal:

echo $SSH_AUTH_SOCK

Depois adicione-o à configuração:

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "env": {
        "DEVICE_USERNAME": "admin",
        "SSH_AUTH_SOCK": "/private/tmp/com.apple.launchd.XXXXX/Listeners"
      }
    }
  }
}

Observe que o caminho do socket muda a cada reinicialização e deve ser atualizado na configuração de acordo.

Alternativamente, usando autenticação por senha:

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "env": {
        "DEVICE_USERNAME": "admin",
        "DEVICE_PASSWORD": "mysecret"
      }
    }
  }
}

Reinicie o Claude Desktop após editar a configuração.

Exemplos de prompts

Mostre-me a configuração ativa de 10.0.0.1
Compare as configurações ativas de n9k-1 e n9k-2 e resuma as diferenças
Verifique o status do vizinho BGP no arista1 e me diga se alguma sessão está inativa
Obtenha o status das interfaces de 10.0.0.1 e liste quaisquer interfaces que estejam inativas
Revise a configuração ativa de 10.0.0.1 e sinalize quaisquer preocupações de segurança
Obtenha os vizinhos LLDP de 10.0.0.1 e desenhe um diagrama de topologia
Como o tráfego para 192.168.100.0/24 é encaminhado em 10.0.0.1?
Verifique a consistência do NTP em 10.0.0.1, 10.0.0.2 e 10.0.0.3
Descubra os vizinhos do spine-1 via LLDP/CDP e verifique a configuração da malha EVPN
Diga-me exatamente quais comandos usar para corrigir os problemas de configuração que você detectou
Verifique se todos os problemas identificados anteriormente estão corrigidos agora
Execute ping em 10.0.0.2 a partir de 10.0.0.1 e me diga se está alcançável
Verifique se o arista1 consegue alcançar todos os seus peers BGP executando ping em cada um
Execute ping em 8.8.8.8 a partir do VRF de gerenciamento no n9k-1
Execute traceroute do arista1 para 10.0.0.2 e mostre-me o caminho
Execute um traceroute do spine-1 para cada um de seus peers BGP e identifique quaisquer caminhos assimétricos

Ofuscação

Valores sensíveis são ofuscados por padrão na saída de get_config e run_show_command. A ferramenta run_ping não é afetada — a saída de ping não contém valores sensíveis. Para desabilitar a ofuscação, passe --no-obfuscate:

netdev-ssh-mcp --no-obfuscate

Em um arquivo de configuração MCP, passe-o via args:

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "args": ["--no-obfuscate"]
    }
  }
}

Logging

O servidor registra logs em stderr (nunca em stdout, que é reservado para o protocolo MCP). O nível de log é controlado pela variável de ambiente LOG_LEVEL:

Valor	Descrição
`debug`	Detalhes de conexão, strings de comando, contagens de bytes
`info`	Padrão — chamadas de ferramenta, conectar/desconectar, sucesso/falha
`warn`	Apenas avisos
`error`	Apenas erros

LOG_LEVEL=debug netdev-ssh-mcp

Autor

Krzysztof Ciepłucha

Aviso Legal

Esta ferramenta foi projetada e construída com a assistência de ferramentas de IA. As decisões de design, a arquitetura e todo o código foram revisados e verificados por um humano. O projeto passa por verificações de segurança automatizadas, varredura de vulnerabilidades e análise estática de código a cada commit.

Dito isso, este software é fornecido como está, sem garantias. Pode conter bugs. Use por sua conta e risco.

Licença

Licenciado sob a Apache License, Versão 2.0. Consulte LICENSE para detalhes.