wiki/ssh-mcp/API.md

← 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 · MokoStandards

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