← [Home](Home)

# API Reference

ssh-mcp exposes 37 MCP tools organized into 6 groups. Every tool accepts its parameters as a JSON object and returns a text response.

---

## Core (5 tools)

Essential SSH operations: execute commands, transfer files, list servers.

### ssh_execute

Execute a command on a remote SSH server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name from configuration |
| `command` | string | Yes | Command to execute |
| `cwd` | string | No | Working directory (uses server default if configured) |
| `timeout` | number | No | Timeout in ms (default: 120000, max: 300000) |

### ssh_upload

Upload a file to a remote SSH server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `localPath` | string | Yes | Local file path |
| `remotePath` | string | Yes | Remote destination path |

### ssh_download

Download a file from a remote SSH server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `remotePath` | string | Yes | Remote file path |
| `localPath` | string | Yes | Local destination path |

### ssh_sync

Synchronize files and folders between local and remote via rsync.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `source` | string | Yes | Source path (prefix with `local:` or `remote:`) |
| `destination` | string | Yes | Destination path (prefix with `local:` or `remote:`) |
| `exclude` | string[] | No | Patterns to exclude |
| `dryRun` | boolean | No | Preview without making changes |
| `delete` | boolean | No | Delete files in destination not in source |
| `compress` | boolean | No | Compress during transfer (default: true) |
| `verbose` | boolean | No | Show detailed progress |
| `checksum` | boolean | No | Use checksum instead of timestamp comparison |
| `timeout` | number | No | Timeout in ms (default: 30000) |

### ssh_list_servers

List all configured SSH servers. Takes no parameters.

---

## Sessions (4 tools)

Persistent SSH sessions that maintain working directory state across commands.

### ssh_session_start

Start a persistent SSH session.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `name` | string | No | Optional session name for identification |

### ssh_session_send

Send a command to an existing SSH session.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session` | string | Yes | Session ID from `ssh_session_start` |
| `command` | string | Yes | Command to execute in the session |
| `timeout` | number | No | Timeout in ms (default: 30000) |

### ssh_session_list

List all active SSH sessions.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | No | Filter by server name |

### ssh_session_close

Close an SSH session.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session` | string | Yes | Session ID to close, or `"all"` to close all |

---

## Monitoring (6 tools)

System health checks, service monitoring, process management, log tailing, and alerting.

### ssh_health_check

Perform a comprehensive health check on a remote server (CPU, memory, disk, network, load average, uptime).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `detailed` | boolean | No | Include detailed metrics |

### ssh_service_status

Check the status of services on a remote server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `services` | string[] | Yes | Service names (e.g., `["nginx", "mysql", "docker"]`) |

### ssh_process_manager

List, inspect, or kill processes on a remote server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `action` | enum | Yes | `list`, `kill`, or `info` |
| `pid` | number | No | Process ID (for `kill` / `info`) |
| `signal` | enum | No | Signal: `TERM`, `KILL`, `HUP`, `INT`, `QUIT` |
| `sortBy` | enum | No | Sort by `cpu` or `memory` |
| `limit` | number | No | Max processes to return |
| `filter` | string | No | Filter by process name |

### ssh_alert_setup

Configure health monitoring alert thresholds.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `action` | enum | Yes | `set`, `get`, or `check` |
| `cpuThreshold` | number | No | CPU usage percentage threshold |
| `memoryThreshold` | number | No | Memory usage percentage threshold |
| `diskThreshold` | number | No | Disk usage percentage threshold |
| `enabled` | boolean | No | Enable or disable alerts |

### ssh_tail

Tail remote log files.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `file` | string | Yes | Path to the log file |
| `lines` | number | No | Initial lines to show (default: 10) |
| `follow` | boolean | No | Follow for new content (default: true) |
| `grep` | string | No | Filter lines with a grep pattern |

### ssh_monitor

Monitor system resources (CPU, RAM, disk, network, processes) on a remote server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `type` | enum | No | `overview`, `cpu`, `memory`, `disk`, `network`, or `process` (default: `overview`) |
| `interval` | number | No | Update interval in seconds (continuous mode) |
| `duration` | number | No | Duration in seconds (continuous mode) |

---

## Backup (4 tools)

Create, list, restore, and schedule backups for databases and files.

### ssh_backup_create

Create a backup of a database or file set on a remote server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `type` | enum | Yes | `mysql`, `postgresql`, `mongodb`, `files`, or `full` |
| `name` | string | Yes | Backup name (e.g., `production`) |
| `database` | string | Cond. | Database name (required for db types) |
| `dbUser` | string | No | Database user |
| `dbPassword` | string | No | Database password |
| `dbHost` | string | No | Database host (default: localhost) |
| `dbPort` | number | No | Database port |
| `paths` | string[] | Cond. | Paths to backup (required for `files` type) |
| `exclude` | string[] | No | Patterns to exclude |
| `backupDir` | string | No | Remote backup directory (default: `/var/backups/ssh-manager`) |
| `retention` | number | No | Retention in days (default: 7) |
| `compress` | boolean | No | Compress backup (default: true) |

### ssh_backup_list

List available backups on a remote server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `type` | enum | No | Filter by backup type |
| `backupDir` | string | No | Backup directory |

### ssh_backup_restore

Restore from a backup on a remote server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `backupId` | string | Yes | Backup ID to restore |
| `database` | string | No | Target database name |
| `dbUser` | string | No | Database user |
| `dbPassword` | string | No | Database password |
| `dbHost` | string | No | Database host |
| `dbPort` | number | No | Database port |
| `targetPath` | string | No | Target path for file restores (default: `/`) |
| `backupDir` | string | No | Backup directory |

### ssh_backup_schedule

Schedule automatic backups using cron on the remote server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `schedule` | string | Yes | Cron expression (e.g., `0 2 * * *`) |
| `type` | enum | Yes | `mysql`, `postgresql`, `mongodb`, or `files` |
| `name` | string | Yes | Backup name |
| `database` | string | No | Database name (for db types) |
| `paths` | string[] | No | Paths to backup (for `files` type) |
| `retention` | number | No | Retention in days (default: 7) |

---

## Database (4 tools)

Database operations for MySQL, PostgreSQL, and MongoDB.

### ssh_db_dump

Dump a database to a file on the remote server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `type` | enum | Yes | `mysql`, `postgresql`, or `mongodb` |
| `database` | string | Yes | Database name |
| `outputFile` | string | Yes | Output file path on remote server |
| `dbUser` | string | No | Database user |
| `dbPassword` | string | No | Database password |
| `dbHost` | string | No | Database host (default: localhost) |
| `dbPort` | number | No | Database port |
| `compress` | boolean | No | Gzip output (default: true) |
| `tables` | string[] | No | Specific tables to dump (MySQL/PostgreSQL) |

### ssh_db_import

Import a database from an SQL file on the remote server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `type` | enum | Yes | `mysql`, `postgresql`, or `mongodb` |
| `database` | string | Yes | Target database name |
| `inputFile` | string | Yes | Input file path on remote server |
| `dbUser` | string | No | Database user |
| `dbPassword` | string | No | Database password |
| `dbHost` | string | No | Database host (default: localhost) |
| `dbPort` | number | No | Database port |
| `drop` | boolean | No | Drop existing data before import (MongoDB, default: true) |

### ssh_db_list

List databases, or tables/collections within a database.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `type` | enum | Yes | `mysql`, `postgresql`, or `mongodb` |
| `database` | string | No | Database name (omit to list all databases) |
| `dbUser` | string | No | Database user |
| `dbPassword` | string | No | Database password |
| `dbHost` | string | No | Database host (default: localhost) |
| `dbPort` | number | No | Database port |

### ssh_db_query

Execute a read-only SELECT query against a database. Mutating statements (`INSERT`, `UPDATE`, `DELETE`, `DROP`, etc.) are rejected.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name |
| `type` | enum | Yes | `mysql`, `postgresql`, or `mongodb` |
| `database` | string | Yes | Database name |
| `query` | string | Yes | SQL SELECT query, or MongoDB find query |
| `collection` | string | No | MongoDB collection name |
| `dbUser` | string | No | Database user |
| `dbPassword` | string | No | Database password |
| `dbHost` | string | No | Database host (default: localhost) |
| `dbPort` | number | No | Database port |

---

## Advanced (14 tools)

Deployment, sudo, tunnels, groups, aliases, hooks, profiles, and more.

### ssh_execute_sudo

Execute a command with sudo on a remote server.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name or alias |
| `command` | string | Yes | Command to execute with sudo |
| `password` | string | No | Sudo password (masked in output) |
| `cwd` | string | No | Working directory |
| `timeout` | number | No | Timeout in ms (default: 30000) |

### ssh_execute_group

Execute a command on a group of servers.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `group` | string | Yes | Group name (e.g., `production`, `all`) |
| `command` | string | Yes | Command to execute |
| `strategy` | enum | No | `parallel`, `sequential`, or `rolling` |
| `delay` | number | No | Delay between servers in ms (for rolling) |
| `stopOnError` | boolean | No | Stop on first error |
| `cwd` | string | No | Working directory |

### ssh_group_manage

Manage server groups (create, update, delete, list, add/remove servers).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | enum | Yes | `create`, `update`, `delete`, `list`, `add-servers`, `remove-servers` |
| `name` | string | No | Group name |
| `servers` | string[] | No | Server names |
| `description` | string | No | Group description |
| `strategy` | enum | No | Default execution strategy |
| `delay` | number | No | Default delay between servers |
| `stopOnError` | boolean | No | Default stop-on-error behavior |

### ssh_deploy

Deploy files to a remote server with automatic permission handling and optional service restart.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name or alias |
| `files` | object[] | Yes | Array of `{ local, remote }` file mappings |
| `options.owner` | string | No | File owner (e.g., `user:group`) |
| `options.permissions` | string | No | File permissions (e.g., `644`) |
| `options.backup` | boolean | No | Backup existing files (default: true) |
| `options.restart` | string | No | Service to restart after deploy |
| `options.sudoPassword` | string | No | Sudo password if needed |

### ssh_command_alias

Manage command aliases for frequently used commands.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | enum | Yes | `add`, `remove`, `list`, or `suggest` |
| `alias` | string | No | Alias name (for add/remove) |
| `command` | string | No | Command to alias (for add), or search term (for suggest) |

### ssh_hooks

Manage automation hooks for SSH operations.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | enum | Yes | `list`, `enable`, `disable`, or `status` |
| `hook` | string | No | Hook name (for enable/disable) |

### ssh_profile

Manage SSH Manager profiles for different project types.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | enum | Yes | `list`, `switch`, or `current` |
| `profile` | string | No | Profile name (for switch) |

### ssh_connection_status

Check SSH connection pool status and manage connections.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | enum | Yes | `status`, `reconnect`, `disconnect`, or `cleanup` |
| `server` | string | No | Server name (for reconnect/disconnect) |

### ssh_tunnel_create

Create an SSH tunnel (local port forwarding, remote port forwarding, or SOCKS proxy).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | Server name or alias |
| `type` | enum | Yes | `local`, `remote`, or `dynamic` |
| `localHost` | string | No | Local bind address (default: `127.0.0.1`) |
| `localPort` | number | Yes | Local port |
| `remoteHost` | string | No | Remote host (not needed for `dynamic`) |
| `remotePort` | number | No | Remote port (not needed for `dynamic`) |

### ssh_tunnel_list

List active SSH tunnels.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | No | Filter by server name |

### ssh_tunnel_close

Close an SSH tunnel. One of `tunnelId` or `server` must be provided.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tunnelId` | string | No | Tunnel ID to close |
| `server` | string | No | Close all tunnels for this server |

### ssh_key_manage

Manage SSH host keys for security verification.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | enum | Yes | `verify`, `accept`, `remove`, `list`, or `check` |
| `server` | string | No | Server name (required for most actions) |
| `autoAccept` | boolean | No | Auto-accept new keys (use with caution) |

### ssh_alias

Manage server aliases for easier access.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | enum | Yes | `add`, `remove`, or `list` |
| `alias` | string | No | Alias name (for add/remove) |
| `server` | string | No | Server name (for add) |

### ssh_history

View SSH command history.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Number of entries (default: 20) |
| `server` | string | No | Filter by server name |
| `success` | boolean | No | Filter by success/failure |
| `search` | string | No | Search in command strings |

---

*Repo: [ssh-mcp](https://git.mokoconsulting.tech/MokoConsulting/ssh-mcp) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*

| Revision | Date | Author | Description |
|---|---|---|---|
| 1.0 | 2026-05-09 | Moko Consulting | Initial version |