mcp-secure-shell

A Rust MCP (Model Context Protocol) server for SSH/SFTP remote shell execution and file transfer. This allows AI agents to execute commands on remote hosts as easily as executing local shell commands.

Features

• SSH Command Execution: Execute shell commands on remote hosts via SSH
• SFTP File Transfer: Upload and download files to/from remote hosts
• SSH Config Support: Uses your existing ~/.ssh/config file for host configurations
• Key-based Authentication: Supports SSH key-based authentication (no password auth)
• Connection Pooling: Maintains connections for efficient repeated operations

Prerequisites

1. SSH Key Setup: Ensure SSH key-based authentication is configured for your target hosts
2. SSH Config: Configure your hosts in ~/.ssh/config (optional but recommended)
3. SFTP Enabled: For file transfer, ensure SFTP is enabled on the remote server (Subsystem sftp internal-sftp in sshd_config)

Installation

cargo install --path .

Or build from source:

cargo build --release

The binary will be at target/release/mcp-secure-shell.

MCP Server Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "ssh": {
      "command": "/path/to/mcp-secure-shell",
      "args": []
    }
  }
}

Available Tools

ssh_exec

Execute a shell command on a remote host.

Parameters:

• host (required): SSH host alias from ~/.ssh/config or direct hostname
• command (required): Shell command to execute
• cwd (optional): Working directory to run the command from

Example:

{
  "host": "myserver",
  "command": "ls -la /var/log",
  "cwd": "/home/user"
}

sftp_upload

Upload a local file to a remote host.

Parameters:

• host (required): SSH host alias or hostname
• local_path (required): Path to the local file
• remote_path (required): Destination path on the remote host

Example:

{
  "host": "myserver",
  "local_path": "/tmp/myfile.txt",
  "remote_path": "/home/user/myfile.txt"
}

sftp_download

Download a file from a remote host.

Parameters:

• host (required): SSH host alias or hostname
• remote_path (required): Path to the file on the remote host
• local_path (required): Destination path on the local machine

Example:

{
  "host": "myserver",
  "remote_path": "/var/log/app.log",
  "local_path": "/tmp/app.log"
}

ssh_list_hosts

List all SSH hosts configured in ~/.ssh/config.

Parameters: None

ssh_host_info

Get connection details for a specific SSH host.

Parameters:

• host (required): SSH host alias to get info for

SSH Config Example

# ~/.ssh/config

Host myserver
    HostName 192.168.1.100
    User admin
    Port 22
    IdentityFile ~/.ssh/id_ed25519

Host devbox
    HostName dev.example.com
    User developer
    IdentityFile ~/.ssh/id_rsa

Environment Variables

• RUST_LOG: Set logging level (e.g., RUST_LOG=mcp_secure_shell=debug)

Security Considerations

• This server executes commands on remote hosts with the permissions of the configured SSH user
• Only key-based authentication is supported (no password authentication)
• Host keys are verified against ~/.ssh/known_hosts by default
• Be cautious about which hosts are configured and accessible
• Connection timeout is set to 30 seconds to prevent hanging

Development

Building

cargo build

Running Tests

Unit tests:

cargo test

Integration tests (requires Docker):

1. Start the test SSHD container:

   ./scripts/test-sshd.sh start

2. Run integration tests:

   cargo test --test integration_test

3. Stop the container when done:

   ./scripts/test-sshd.sh stop

Test Container

The project includes a Docker-based test environment using panubo/sshd, a minimal Alpine Linux image with OpenSSH.

Container management:

./scripts/test-sshd.sh start    # Start container
./scripts/test-sshd.sh stop     # Stop container
./scripts/test-sshd.sh status   # Check status
./scripts/test-sshd.sh test     # Test SSH connection
./scripts/test-sshd.sh logs     # View logs
./scripts/test-sshd.sh shell    # Open shell in container

Environment variables:

• SSH_PORT: Port to expose SSHD on (default: 2222)
• TEST_SSH_HOST: Host for integration tests (default: localhost)
• TEST_SSH_PORT: Port for integration tests (default: 2222)
• TEST_SSH_USER: User for integration tests (default: root)

Docker Compose alternative:

docker compose -f docker-compose.test.yml up -d

Adding to SSH Config for Manual Testing

After starting the test container, add this to ~/.ssh/config:

Host test-container
    HostName localhost
    Port 2222
    User root
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

Then test the MCP server with the test-container host.

License

MIT