ssh-mcp

ssh-mcp

Documentación en inglés | 中文说明

Servidor MCP SSH local para agentes compatibles con MCP | Puente MCP local orientado a operaciones de IA

ssh-mcp es un servidor MCP SSH local disponible para agentes/clientes de IA compatibles con MCP, que mediante Model Context Protocol (MCP) sobre stdio permite a la IA usar los hosts Linux SSH, bases de datos MySQL/MariaDB y PostgreSQL registrados en tu máquina local para solucionar problemas, consultar, ver archivos y desplegar archivos.

No es un proxy en la nube ni escucha en puertos HTTP/TCP. Los objetivos, credenciales de conexión y huellas de host son gestionados por un daemon local; el usuario registra objetivos mediante TUI, y los clientes MCP invocan los objetivos registrados a través de stdio.

Vista previa de la interfaz

Ejemplo de consola local; las direcciones y cuentas en la imagen son datos de demostración.

Interfaz de administración local cuando el almacén de credenciales está bloqueado.

Por qué usarlo

• Una sola entrada para operaciones diarias: comandos SSH, SQL, lectura restringida de archivos, despliegue de archivos y sesiones de trabajo SSH se ofrecen a través de MCP.
• Objetivos claros: solo se puede acceder a objetivos registrados y habilitados localmente; no se escanea la red ni se entregan credenciales a la IA o a los clientes MCP.
• Límites de seguridad definidos: las solicitudes de operación rutinarias se ejecutan directamente; categorías de alto riesgo fijas como formatear discos, dañar directorios del sistema o escrituras masivas incondicionales se bloquean antes del envío; cada objetivo SSH también puede configurar listas negras de expresiones regulares.
• Despliegue verificable: el despliegue de archivos primero valida tamaño y SHA-256, luego crea un archivo temporal, respalda el archivo existente y activa el nuevo; si el resultado es desconocido, se conserva la información necesaria para verificación y recuperación manual, sin reintentos automáticos.
• Local y multiplataforma: el programa puede ejecutarse en Linux, macOS y Windows; el SSH remoto actualmente admite semántica de comandos Linux.

Cómo 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 es el puente stdio que usan los clientes MCP. Se conecta o inicia el daemon local según sea necesario; el daemon gestiona exclusivamente el estado local, las credenciales y las conexiones remotas. manage abre la TUI para desbloquear el almacén de credenciales, registrar objetivos y realizar copias de seguridad. Los resultados remotos se devuelven como datos MCP estructurados y se marcan como salida remota no confiable.

Inicio rápido

Instalación automática mediante IA

Envía la siguiente frase a un agente con permisos de terminal y manipulación de archivos, y que pueda configurar un servidor MCP local:

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

En el primer uso, aún debes configurar la contraseña maestra, registrar objetivos y confirmar las huellas de host SSH en la TUI local; solo los clientes que admitan iniciar un servidor MCP stdio local pueden conectarse directamente.

Instalación manual o compilación

Cuando la página de versiones ofrezca binarios precompilados, descarga el archivo que coincida con tu plataforma; los nombres de archivo y enlaces de descarga están en Instalación y ejecución. Si no hay una versión compatible, compila desde el código fuente.

Se requiere Go 1.26.5, un agente/cliente compatible con MCP stdio y un entorno de escritorio local con terminal interactiva.

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

Al abrir la TUI por primera vez, configura la contraseña maestra y luego agrega y verifica objetivos SSH o de bases de datos (en la página principal, presiona e para alternar entre chino e inglés; la preferencia se guarda automáticamente). Tras la verificación, conecta el servidor MCP stdio según el formato de configuración de tu agente/cliente. El contrato de configuración general es el siguiente (los nombres de campos pueden variar según el cliente):

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

A continuación, un ejemplo de registro para Codex CLI:

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

Indica explícitamente "usar ssh-mcp" en la tarea de tu agente/cliente, por ejemplo:

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

Los pasos completos están en Inicio rápido y los parámetros de herramientas en Referencia de herramientas MCP.

Alcance de soporte

Ámbito	Contenido soportado
Host local	Linux, macOS, Windows
SSH remoto	IP registrada, autenticación directa con contraseña, huella de host confirmada; los comandos remotos se ejecutan con semántica Linux
Bases de datos	MySQL/MariaDB, PostgreSQL, registradas mediante IP:端口
Métodos de autenticación	SSH actualmente con contraseña; las bases de datos configuran cuentas de solo lectura y cuentas de escritura opcionales
Clientes MCP	Agentes/clientes que admiten iniciar un servidor MCP stdio local; Codex CLI es solo un ejemplo de configuración
Transporte MCP	stdio; el daemon local usa IPC del sistema operativo local

Las claves privadas SSH/agente, semántica de comandos remotos Windows o macOS, TTY interactivo, reenvío de puertos independiente o persistente y objetivos no registrados no están dentro del alcance actual; el reenvío SSH estático en comandos aún debe apuntar a objetivos registrados y pasar la verificación de políticas; el reenvío dinámico se rechaza.

Documentación

• Índice de documentación
• Inicio rápido
• Guía de uso
• Instalación y ejecución
• Configuración de objetivos
• Referencia de herramientas MCP
• Modelo de seguridad y limitaciones
• Mantenimiento diario
• Cómo funciona y arquitectura
• Contribuciones
• Lista de publicación de código abierto

Licencia

Este proyecto se publica bajo GNU General Public License v3.0.