MokoConsulting/wiki
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
Files
main
wiki/ssh-mcp/API.md
T
gitea-actions[bot] 47183ee5ef docs: sync wikis from Gitea (2026-05-10 00:09 UTC)
2026-05-09 19:09:43 -05:00

479 lines
17 KiB
Markdown
Raw Permalink Blame History

← [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 |
Reference in New Issue View Git Blame Copy Permalink