ssh-mcp

ssh-mcp

Documentação em inglês | 中文说明

Servidor SSH MCP local para agentes compatíveis com MCP | Ponte MCP local para operações de IA em infraestrutura

ssh-mcp é um servidor SSH MCP local disponível para agentes/clientes de IA compatíveis com MCP, que usa o Model Context Protocol (MCP) via stdio para permitir que a IA utilize os hosts Linux SSH, bancos de dados MySQL/MariaDB e PostgreSQL registrados na sua máquina, realizando diagnóstico, consultas, visualização de arquivos e implantação de arquivos.

Não é um proxy em nuvem e não escuta portas HTTP/TCP. Os alvos, credenciais de conexão e impressões digitais dos hosts são gerenciados por um daemon local; o usuário registra os alvos via TUI, e o cliente MCP chama os alvos registrados via stdio.

Pré-visualização da interface

Exemplo de console local; endereços e contas na imagem são dados de demonstração da documentação.

Interface de gerenciamento local quando o cofre de credenciais está bloqueado.

Por que usar

• Um único ponto de entrada para operações diárias: comandos SSH, SQL, leitura restrita de arquivos, implantação de arquivos e sessões de trabalho SSH são fornecidos via MCP.
• Alvos bem definidos: somente alvos registrados e habilitados localmente podem ser acessados; não há varredura de rede e as credenciais não são entregues à IA ou ao cliente MCP.
• Limites de segurança claros: solicitações de operação rotineiras são executadas diretamente; categorias fixas de alto risco, como formatar disco, danificar diretórios do sistema ou gravação em massa incondicional, são bloqueadas antes do envio; cada alvo SSH também pode ter uma lista negra de regex configurada.
• Implantação verificável: a implantação de arquivos valida tamanho e SHA-256 antes de criar arquivo temporário, fazer backup do arquivo existente e ativar o novo arquivo; quando o resultado é desconhecido, as informações necessárias para verificação e recuperação manual são preservadas, sem nova tentativa automática.
• Local e multiplataforma: o programa roda em Linux, macOS e Windows; o SSH remoto atualmente suporta semântica de comandos Linux.

Como funciona

flowchart LR
    C["MCP-compatible Agent / client"] -->|MCP / stdio| B["ssh-mcp bridge"]
    B --> D["本地 daemon"]
    U["本地 TUI"] --> D
    D --> S["登记目标与凭据库"]
    D --> R["SSH / SFTP / MySQL / PostgreSQL"]
    R --> D --> B --> C

serve é a ponte stdio usada pelo cliente MCP. Ele conecta ou inicia o daemon local conforme necessário; o daemon detém exclusivamente o estado local, credenciais e conexões remotas. manage abre a TUI para desbloquear o cofre de credenciais, registrar alvos e executar backups. Resultados remotos são retornados como dados MCP estruturados e marcados como saída remota não confiável.

Início rápido

Instalação automática via IA

Envie a frase abaixo a um agente com permissão de terminal e manipulação de arquivos, capaz de configurar um servidor MCP local:

请从 https://github.com/lswzw/ssh-mcp/releases/latest 下载适合当前系统和架构的 ssh-mcp 预编译版本，
放到稳定路径并注册为当前 MCP 客户端的 stdio server（启动参数为 serve），
完成后验证工具列表；如果客户端不支持本地 stdio，
或需要主密码、目标登记、主机指纹确认，请提示我手动完成。

No primeiro uso, ainda é necessário definir a senha mestra na TUI local, registrar alvos e confirmar as impressões digitais dos hosts SSH; somente clientes que suportam iniciar um servidor MCP stdio local podem se conectar diretamente.

Instalação manual ou compilação

Quando a página de releases oferecer binários pré-compilados, baixe o arquivo correspondente à sua plataforma; nomes de arquivo e endereços de download estão em Instalação e execução. Se não houver versão compatível, compile a partir do código-fonte.

Requer Go 1.26.5, um agente/cliente compatível com MCP via stdio e um ambiente desktop local com terminal interativo.

git clone https://github.com/lswzw/ssh-mcp.git
cd ssh-mcp
make build
./bin/ssh-mcp manage

Na primeira abertura da TUI, defina a senha mestra e adicione/valide alvos SSH ou de banco de dados (na página inicial, pressione e para alternar entre os idiomas chinês e inglês; a preferência é persistida automaticamente). Após a validação, conecte o servidor MCP stdio conforme o formato de configuração do seu agente/cliente. O contrato de configuração genérico é o seguinte (os nomes dos campos podem variar conforme o cliente):

transport: stdio
command: /absolute/path/to/bin/ssh-mcp
args: ["serve"]

Abaixo está um exemplo de registro no Codex CLI:

codex mcp add ssh-mcp -- "$PWD/bin/ssh-mcp" serve
codex mcp get ssh-mcp

Na tarefa do seu agente/cliente, indique explicitamente "use ssh-mcp", por exemplo:

使用 ssh-mcp 检查已登记生产主机的磁盘空间，并报告占用最高的目录。

Passos completos em Início rápido; parâmetros das ferramentas em Referência de ferramentas MCP.

Escopo de suporte

Escopo	Conteúdo suportado
Host local	Linux, macOS, Windows
SSH remoto	IPs registrados, autenticação por senha direta, impressões digitais confirmadas; comandos remotos executados com semântica Linux
Bancos de dados	MySQL/MariaDB, PostgreSQL, registrados via IP:端口
Autenticação	SSH atualmente com senha; bancos de dados com conta somente leitura e conta opcional de escrita
Cliente MCP	Agentes/clientes que suportam iniciar servidor MCP stdio local; Codex CLI é apenas exemplo de configuração
Transporte MCP	stdio; o daemon local usa IPC do sistema operacional

Chaves privadas SSH/agent, semântica de comandos Windows ou macOS remotos, TTY interativo, encaminhamento de porta persistente ou independente e alvos não registrados estão fora do escopo atual; encaminhamento SSH estático em comandos ainda deve apontar para alvos registrados e passar pela verificação de política; encaminhamento dinâmico é rejeitado.

Documentação

• Índice da documentação
• Início rápido
• Guia de uso
• Instalação e execução
• Configuração de alvos
• Referência de ferramentas MCP
• Modelo de segurança e limitações
• Manutenção diária
• Como funciona e arquitetura
• Contribuição
• Lista de publicação de código aberto

Licença

Este projeto é distribuído sob a GNU General Public License v3.0.