SSH Remote File MCP Server

Lee, edita y ejecuta comandos en un servidor remoto a través de Claude Code — como si los archivos fueran locales.

Un MCP servidor que expone un host SSH remoto como un conjunto de herramientas de sistema de archivos. Una vez registrado con Claude Code puedes pedirle que lea /home/you/proj/main.py, edite una función, ejecute pytest, o haga grep en el árbol remoto — y habla con el servidor a través de SSH, con alcance de rutas y filtrado de comandos en el camino.

中文文档 / Chinese version → · GitHub →

Licencia

MIT — ver LICENSE.

Related MCP server: MCP SSH Server

Características

Inicio rápido

# 1. Clone and enter
git clone https://github.com/zhangqi-eiq/server_mcp.git
cd server_mcp

# 2. Install (editable mode — picks up code changes immediately)
python install.py

# 3. Edit your real credentials
#    (file is at ~/.ssh-mcp-server/config.json by default)

# 4. Restart Claude Code, then in a chat:
#    "show me the env of my server"

Eso es todo. install.py hace tres cosas:

1. pip install -e . — instala el paquete.

2. Copia config.json (con valores de marcador de posición) a ~/.ssh-mcp-server/.

3. Ejecuta claude mcp add para que el servidor aparezca en Claude Code.

Si aún no tienes la CLI de claude, ejecuta python install.py --no-register y añade la entrada MCP manualmente (ver Configuración manual).

Configuración manual

Si prefieres configurarlo a mano, o install.py no se registró correctamente:

1. Instalar el paquete

pip install -e .

Esto coloca ssh_mcp_server en la ruta de importación de Python para que python -m ssh_mcp_server pueda lanzar el servidor.

2. Crear tu configuración

Copia config.json a ~/.ssh-mcp-server/config.json (el cargador busca aquí cuando SSH_MCP_CONFIG no está definido) y completa con valores reales:

mkdir -p ~/.ssh-mcp-server
cp config.json ~/.ssh-mcp-server/config.json
$EDITOR ~/.ssh-mcp-server/config.json

3. Registrar con Claude Code

La entrada MCP debe invocar el servidor a través del intérprete de Python en el que instalaste. <python> a continuación debe ser la ruta absoluta a ese intérprete (sys.executable de tu entorno activado, por ejemplo C:\Users\you\.conda\envs\myenv\python.exe en Windows o /home/you/.venv/bin/python en Linux).

Opción A — ámbito de usuario, disponible en todos los proyectos:

claude mcp add --scope user ssh-remote \
  -e SSH_MCP_CONFIG="$HOME/.ssh-mcp-server/config.json" \
  -- "<python>" -m ssh_mcp_server

Opción B — ámbito de proyecto, solo este proyecto:

Crea .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "ssh-remote": {
      "command": "<absolute path to python>",
      "args": ["-m", "ssh_mcp_server"],
      "env": {
        "SSH_MCP_CONFIG": "/absolute/path/to/your/config.json"
      }
    }
  }
}

Nota: Claude Code busca mcpServers en dos lugares — ~/.claude.json (gestionado por CLI, escrito por claude mcp add) y ~/.claude/settings.json (editado a mano). La ruta CLI anterior escribe en el correcto automáticamente.

Referencia de configuración

Forma de config.json:

{
  "ssh": {
    "host": "your-server.example.com",
    "port": 22,
    "username": "your-username",
    "auth": {
      "type": "password",
      "key_path": "",
      "password": "your-password",
      "key_password": ""
    },
    "connect_timeout": 10,
    "keepalive_interval": 30
  },
  "allowed_paths": [
    "/home/your-username/projects"
  ],
  "security": {
    "blocked_commands": ["rm -rf /", "mkfs", ...],
    "max_file_size_mb": 50,
    "max_output_chars": 100000,
    "command_timeout": 30
  }
}

Conexión SSH

Control de acceso

• allowed_paths — lista blanca de directorios remotos. Cadai operación de archivo se valida contra esta lista después de la normalización de ... Las solicitudes fuera de la lista se rechazan. Las sub-rutas heredan el acceso (por ejemplo, /data/proj permite /data/proj/sub/file.py).

• security.blocked_commands — lista de patrones de comandos de shell que ssh_run_command se niega a ejecutar. Los valores predeterminados cubren errores obvios (rm -rf /, mkfs, shutdown, bombas fork, escrituras directas a dispositivos de bloque). Puedes ampliar la lista, pero nunca la debilites para "arreglar" una necesidad legítima — ver Modelo de seguridad.

Límites de recursos

Autenticación

Basada en clave (recomendada)

# On your local machine
ssh-keygen -t ed25519 -C "you@example.com"

# Push the public key to the remote
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server

Luego en config.json:

"auth": {
  "type": "key",
  "key_path": "~/.ssh/id_ed25519",
  "key_password": ""
}

key_password solo es necesario si la clave privada está cifrada.

Basada en contraseña

"auth": {
  "type": "password",
  "password": "your-password"
}

La contraseña se almacena en texto plano en config.json. Prefiere la autenticación por clave.

Gestor GUI (opcional)

Una pequeña GUI basada en Tk te permite mantener múltiples perfiles de servidor y cambiar entre ellos:

# From source
python server_manager.py

# Or build a standalone Windows exe and put it on PATH
pip install -e ".[gui]"   # adds pyinstaller
python build.py
python setup_global.py
# now `SSH-Server-Manager` is on PATH

Los perfiles viven en profiles.json; al cambiar, se copia el perfil seleccionado a config.json para que el servidor MCP lo recoja en el próximo lanzamiento.

Modelo de seguridad

Este servidor es intencionalmente conservador. Dos capas independientes protegen el host remoto:

1. Alcance de rutas. Cada operación de archivo se normaliza (resolviendo .., colapsando barras) y luego se verifica contra allowed_paths. No hay forma de escapar de la lista — la verificación ocurre en el lado del servidor después de que la ruta se resuelve en el remoto.

2. Filtrado de comandos. ssh_run_command rechaza cualquier comando que coincida con security.blocked_commands (coincidencia de subcadena). La lista predeterminada bloquea destrucción recursiva, escrituras directas a dispositivos, apagado del sistema, bombas fork y instaladores de shell remotos (curl … | sh). Amplía la lista si necesitas permitir algo específico — pero no la vacíes.

Cosas que este servidor no hace:

• No se ejecuta como root en el remoto. Conéctate por SSH a un usuario no root.

• No omite sudo. Si el usuario configurado no puede usar sudo, tampoco puede el servidor.

• No proporciona un shell interactivo. Los procesos de larga duración se matan con command_timeout.

Solución de problemas

Estructura del proyecto

server/
├── ssh_mcp_server/         # MCP server package (the actual product)
│   ├── server.py           #   tool definitions
│   ├── ssh_client.py       #   paramiko wrapper
│   ├── security.py         #   path + command validation
│   └── config.py           #   config loader
├── server_manager.py       # Tk GUI for managing profiles
├── profiles.json           # GUI profile store
├── config.json             # runtime config template (placeholder values)
├── setup.py                # pip-installable package metadata
├── install.py              # one-shot installer (install + register)
├── setup_global.py         # optional: deploy GUI exe to PATH
├── build.py                # optional: PyInstaller wrapper for the GUI
├── SSH-Server-Manager.spec # PyInstaller spec for fine-grained builds
├── requirements.txt        # raw dependency pins
├── LICENSE                 # MIT
├── README.md               # this file (English)
└── README.zh.md            # Chinese translation

Licencia

MIT — ver el archivo para el texto completo.