mcp-remote-exec

This MCP server provides SSH access to remote servers, enabling an AI assistant to execute shell commands, transfer files via SFTP, and perform remote management tasks. Core features include executing bash commands on remote hosts, uploading and downloading files, and automatic connection cleanup. When ImageKit or Proxmox plugins are enabled, additional capabilities for two-phase file transfers through ImageKit or container management through Proxmox become available. To use, install the server via your preferred Python/uv tooling, configure environment variables for your SSH host(s), and run the MCP using the provided CLI (installable as uv run mcp-remote-exec). Once running, AI prompts can invoke commands like ssh_exec_command, ssh_upload_file, ssh_download_file, and, when plugins are enabled, specialized container and gateway operations.

Prerequisites:

• Python 3.8+ (or a compatible Python runtime)
• Access to install Python tools (e.g., pipx or pip)
• Optional: ImageKit and/or Proxmox accounts if you plan to enable plugins

Installation steps (preferred method using pipx/uv tooling):

1. Install the MCP server package (name inferred from slug):
   • pipx install mcp-remote-exec or, if you install via pipx with a different package name, follow the repository's published package name.
2. Prepare environment variables in a .env file or your runtime environment. Example: I_ACCEPT_RISKS=true HOST=192.168.1.100 SSH_USERNAME=root SSH_PASSWORD=secret ENABLE_IMAGEKIT=true IMAGEKIT_PUBLIC_KEY=your_public_key IMAGEKIT_PRIVATE_KEY=your_private_key IMAGEKIT_URL_ENDPOINT=https://ik.imagekit.io/your_id IMAGEKIT_FOLDER=/mcp-remote-exec ENABLE_PROXMOX=false
3. Run the MCP server using the CLI: uv run mcp-remote-exec or, if you installed differently, follow the runner name exposed by your installation method.

Note: If you prefer a Docker-based setup, consult the repository for a prebuilt image and run commands, adjusting environment variables as needed.

Tips and common issues:

• Ensure SSH credentials are correct and that the target host allows SSH access from the MCP server.
• If enabling ImageKit, provide valid credentials and ensure the ImageKit endpoint is reachable from your deployment environment.
• When using Proxmox, the host must be a Proxmox VE server and ENABLE_PROXMOX should be set to true; if ImageKit is enabled, Proxmox file transfer tools may be replaced by ImageKit tools.
• Review and set I_ACCEPT_RISKS to true to acknowledge the security disclaimer.
• Use timeouts and validation to prevent long-running or untrusted commands from executing unintentionally.
• For production, consider restricting access to the MCP API and enabling auditing/logging of commands and file transfers.