155 lines
3.5 KiB
Markdown
155 lines
3.5 KiB
Markdown
# MCP SSH Tool Usage
|
|
|
|
## Connection Inputs
|
|
|
|
Most tools use these inputs:
|
|
|
|
- `host`: direct remote hostname or IP address.
|
|
- `username`: remote SSH username.
|
|
- `port`: optional remote SSH port, default 22.
|
|
- `keyPath`: optional local private key path. If omitted, the server tries `~/.ssh/id_ed25519`, then `~/.ssh/id_ecdsa`, then `~/.ssh/id_rsa`.
|
|
- `keyPassphrase`: optional passphrase for encrypted private keys. Treat as sensitive.
|
|
|
|
Current limit: do not rely on OpenSSH aliases, SSH agent identities, ProxyJump, ProxyCommand, or `ssh -G` resolution.
|
|
|
|
## `ssh_exec`
|
|
|
|
Use for one bounded remote command.
|
|
|
|
Inputs:
|
|
|
|
- Required: `host`, `username`, `command`.
|
|
- Optional: `cwd`, `port`, `keyPath`, `keyPassphrase`, `timeoutSeconds`.
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"host": "prod-api.example.com",
|
|
"username": "deploy",
|
|
"command": "systemctl status nginx --no-pager",
|
|
"cwd": "/var/www",
|
|
"timeoutSeconds": 30
|
|
}
|
|
```
|
|
|
|
Expected result includes `exitCode`, `stdout`, `stderr`, and `durationMs`. Non-zero exit codes are preserved. Timeout results use `timedOut: true`.
|
|
|
|
## Terminal Session Tools
|
|
|
|
Use for interactive or stateful remote shell work.
|
|
|
|
Start:
|
|
|
|
```json
|
|
{
|
|
"host": "prod-api.example.com",
|
|
"username": "deploy",
|
|
"cols": 120,
|
|
"rows": 40,
|
|
"idleTimeoutSeconds": 900
|
|
}
|
|
```
|
|
|
|
Write:
|
|
|
|
```json
|
|
{
|
|
"sessionId": "term_abc123",
|
|
"input": "pwd\n"
|
|
}
|
|
```
|
|
|
|
Read:
|
|
|
|
```json
|
|
{
|
|
"sessionId": "term_abc123",
|
|
"maxBytes": 12000
|
|
}
|
|
```
|
|
|
|
Stop:
|
|
|
|
```json
|
|
{
|
|
"sessionId": "term_abc123"
|
|
}
|
|
```
|
|
|
|
Operational notes:
|
|
|
|
- Include newline characters when submitting shell commands.
|
|
- Read after each write when command output matters.
|
|
- Stop sessions explicitly after finishing.
|
|
- The remote account's default shell starts without injected setup commands.
|
|
|
|
## `sftp_list`
|
|
|
|
Use to list a remote directory over SFTP.
|
|
|
|
```json
|
|
{
|
|
"host": "prod-api.example.com",
|
|
"username": "deploy",
|
|
"remotePath": "/var/www"
|
|
}
|
|
```
|
|
|
|
Result entries include `name`, `path`, `type`, `size`, and `modifiedUtc`.
|
|
|
|
No SCP fallback is available for directory listing.
|
|
|
|
## `sftp_get`
|
|
|
|
Use to download one remote file into the MCP server working directory.
|
|
|
|
```json
|
|
{
|
|
"host": "prod-api.example.com",
|
|
"username": "deploy",
|
|
"remotePath": "/var/log/app.log",
|
|
"localPath": "downloads/app.log",
|
|
"overwrite": false,
|
|
"maxBytes": 104857600
|
|
}
|
|
```
|
|
|
|
Notes:
|
|
|
|
- Local paths must stay inside the MCP server working directory.
|
|
- Existing local files are not overwritten unless `overwrite` is true.
|
|
- The server tries SFTP first and silently falls back to SCP when SFTP is unavailable.
|
|
|
|
## `sftp_put`
|
|
|
|
Use to upload one local file from the MCP server working directory.
|
|
|
|
```json
|
|
{
|
|
"host": "prod-api.example.com",
|
|
"username": "deploy",
|
|
"localPath": "dist/app.tar.gz",
|
|
"remotePath": "/tmp/app.tar.gz",
|
|
"overwrite": false,
|
|
"maxBytes": 104857600
|
|
}
|
|
```
|
|
|
|
Notes:
|
|
|
|
- Local paths must stay inside the MCP server working directory.
|
|
- Existing remote files are not overwritten unless `overwrite` is true.
|
|
- The server tries SFTP first and silently falls back to SCP when SFTP is unavailable.
|
|
|
|
## Common Error Handling
|
|
|
|
Treat these as actionable errors:
|
|
|
|
- `ssh_key_not_found`: supply `keyPath` or ensure a default key exists.
|
|
- `ssh_authentication_failed`: check `username`, key, and `keyPassphrase`.
|
|
- `invalid_host`, `invalid_username`, `invalid_port`: fix connection inputs.
|
|
- `local_file_exists` or `remote_file_exists`: decide whether `overwrite: true` is appropriate.
|
|
- `unsafe_local_path`: choose a local path inside the MCP server working directory.
|
|
- `download_too_large` or `upload_too_large`: raise `maxBytes` only if the transfer is intended.
|