Content
# SSH MCP Server
An SSH tool service that provides MCP capabilities through `stdio`, supporting remote command execution, and file upload and download via SFTP.
Suitable for connecting to Codex, Claude Desktop, or other MCP clients, exposing the SSH host as a tool.
## Features
- `ssh_list_hosts`: List hosts in the configuration
- `ssh_exec`: Execute commands remotely
- `ssh_upload`: Upload local files or directories
- `ssh_download`: Download remote files or directories
- Supports password, private key, jump host, and `known_hosts` verification
- Supports basic command blacklist/whitelist policies
## Environment Requirements
- Go `1.22+`
- Target host has SSH enabled
## Build
```bash
go build -o ssh-mcp
```
## Quick Start
1. Copy configuration:
```bash
cp config.example.yaml config.yaml
```
2. Modify `config.yaml`
Configure at least one connectable host and set:
- `name`
- `address`
- `user`
- `password` or `private_key_path`
- `host_key.mode`
3. Start the service:
```bash
./ssh-mcp -config ./config.yaml
```
Alternatively:
```bash
SSH_MCP_CONFIG=./config.yaml ./ssh-mcp
```
4. Check if the host is loaded successfully:
```bash
./ssh-mcp -config ./config.yaml -list-hosts
```
## Configuration Example
```yaml
server:
name: "ssh-mcp"
version: "0.1.0"
default_timeout_sec: 120
connect_timeout_sec: 10
max_output_bytes: 1048576
allow_dangerous: false
hosts:
- name: "prod"
address: "1.2.3.4"
port: 22
user: "root"
private_key_path: "~/.ssh/id_ed25519"
host_key:
mode: "known_hosts"
known_hosts_path: "~/.ssh/known_hosts"
policy:
# allow_patterns:
# - "^ls "
# deny_patterns:
# - "(?i)rm\\s+-rf"
```
Configuration highlights:
- `hosts[].name` is the hostname used when calling the tool
- Supports `${ENV_NAME}` environment variable expansion
- `proxy_jump` / `jump_host` can be used for jump hosts
- `host_key.mode` supports `known_hosts` and `insecure_ignore`
- `allow_dangerous: false` enables default dangerous command interception
## Tool Parameters
### `ssh_exec`
- `host`: Hostname
- `command`: Command to execute
- `workdir`: Optional, remote working directory
- `env`: Optional, environment variables
- `timeout_sec`: Optional, timeout in seconds
Commands are executed using `bash -lc`.
### `ssh_upload`
- `host`
- `local_path`
- `remote_path`
- `overwrite`
- `preserve_mode`
### `ssh_download`
- `host`
- `remote_path`
- `local_path`
- `overwrite`
- `preserve_mode`
## Codex Configuration Example
```toml
[mcp_servers.ssh]
command = "/Users/Ng/Documents/ssh-mcp/ssh-mcp"
args = ["-config", "/Users/Ng/Documents/ssh-mcp/config.yaml"]
```
## Security Notes
This project is not a sandbox. `ssh_exec` essentially still executes shell commands on the remote machine. It is recommended to:
- Prioritize private key authentication
- Prioritize `known_hosts`
- Give the remote account minimal permissions
- Configure `policy.allow_patterns` as needed
## License
This project uses the [MIT License](./LICENSE).
