How do I use ssh-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ssh-mcp-server check the system uptime and disk space on the remote server" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

ssh-mcp-server

SSH-based MCP (Model Context Protocol) server for remote command execution and file transfer.

This fork adds optional AstrBot admin validation for all exposed MCP tools.

Chinese README

Features

Execute SSH commands through MCP
Upload files to remote hosts
Download files from remote hosts
List configured SSH servers
Support password, private key, and ~/.ssh/config
Support command whitelist and blacklist
Optional AstrBot admin validation via operatorId

Tools

execute-command
upload
download
list-servers

Install

Recommended for AstrBot

For long-running stdio MCP servers, global install is more stable than letting AstrBot invoke npx every time.

npm install -g @ruawd/ssh-mcp@1.3.4

Then use ssh-mcp as the command in AstrBot.

One-shot usage

npx -y @ruawd/ssh-mcp@1.3.4 --host 192.168.1.1 --port 22 --username root --password pwd123456

AstrBot MCP Examples

Global install

{
  "mcpServers": {
    "sshmcp": {
      "command": "ssh-mcp",
      "args": [
        "--host",
        "192.168.1.1",
        "--port",
        "22",
        "--username",
        "root",
        "--password",
        "pwd123456"
      ]
    }
  }
}

Use `npx`

{
  "mcpServers": {
    "sshmcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ruawd/ssh-mcp@1.3.4",
        "--host",
        "192.168.1.1",
        "--port",
        "22",
        "--username",
        "root",
        "--password",
        "pwd123456"
      ]
    }
  }
}

Private key example

{
  "mcpServers": {
    "sshmcp": {
      "command": "ssh-mcp",
      "args": [
        "--host",
        "192.168.1.1",
        "--port",
        "22",
        "--username",
        "root",
        "--privateKey",
        "~/.ssh/id_rsa"
      ]
    }
  }
}

Use `~/.ssh/config`

{
  "mcpServers": {
    "sshmcp": {
      "command": "ssh-mcp",
      "args": [
        "--host",
        "myserver"
      ]
    }
  }
}

If ~/.ssh/config contains:

Host myserver
    HostName 192.168.1.1
    Port 22
    User root
    IdentityFile ~/.ssh/id_rsa

the server will load those defaults automatically.

CLI Options

--config-file             JSON configuration file path
--ssh-config-file         SSH config file path
--ssh                     SSH connection config in JSON or legacy format
-h, --host                SSH host or host alias from ssh config
-p, --port                SSH port
-u, --username            SSH username
-w, --password            SSH password
-k, --privateKey          SSH private key path
-P, --passphrase          Private key passphrase
-W, --whitelist           Command whitelist (comma-separated regex)
-B, --blacklist           Command blacklist (comma-separated regex)
-s, --socksProxy          SOCKS proxy URL
--pty                     Allocate pseudo-tty for command execution
--pre-connect             Pre-connect configured SSH servers on startup
--require-astrbot-admin   Require operatorId to match allowed admin IDs
--admin-ids               Comma-separated admin IDs, e.g. 10001,10002
--astrbot-config-file     Path to AstrBot data/config/cmd_config.json

AstrBot Admin Validation

This fork can restrict all MCP tools to specific AstrBot administrator IDs.

When enabled, each tool call must include an operatorId.

Two ways to configure administrators:

Directly provide --admin-ids
Read admins_id from AstrBot cmd_config.json

If --admin-ids is present, it takes priority over --astrbot-config-file.

Example with direct admin IDs

{
  "mcpServers": {
    "sshmcp": {
      "command": "ssh-mcp",
      "args": [
        "--host",
        "103.117.136.155",
        "--port",
        "22",
        "--username",
        "root",
        "--password",
        "your-password",
        "--require-astrbot-admin",
        "--admin-ids",
        "1738068535,2653839788"
      ]
    }
  }
}

Example reading AstrBot config

{
  "mcpServers": {
    "sshmcp": {
      "command": "ssh-mcp",
      "args": [
        "--config-file",
        "/path/to/ssh-config.json",
        "--require-astrbot-admin",
        "--astrbot-config-file",
        "/path/to/AstrBot/data/config/cmd_config.json"
      ]
    }
  }
}

Tool call example

{
  "tool": "execute-command",
  "params": {
    "cmdString": "ls -al",
    "connectionName": "prod",
    "operatorId": "1738068535"
  }
}

Important Limitation

AstrBot native MCP integration does not automatically pass the current sender ID to a stdio MCP server.

That means:

this MCP server can validate operatorId
but something upstream still needs to inject the real sender ID

If you are using AstrBot, pair this server with astrbot_plugin_mcp_id_injector, or use your own proxy plugin.

Security Notes

Prefer SSH private keys over passwords
Configure a whitelist for production use
Do not expose the server to untrusted callers
Be careful with upload/download target paths

ssh-mcp-server

ssh-mcp-server

Links

Features

Tools

Install

Recommended for AstrBot

One-shot usage

AstrBot MCP Examples

Global install

Use `npx`

Private key example

Use `~/.ssh/config`

CLI Options

AstrBot Admin Validation

Example with direct admin IDs

Example reading AstrBot config

Tool call example

Important Limitation

Security Notes

Resources

Looking for Admin?

Appeared in Searches

Latest Blog Posts

MCP directory API

ssh-mcp-server

Links

Features

Tools

Install

Recommended for AstrBot

One-shot usage

AstrBot MCP Examples

Global install

Use npx

Private key example

Use ~/.ssh/config

CLI Options

AstrBot Admin Validation

Example with direct admin IDs

Example reading AstrBot config

Tool call example

Important Limitation

Security Notes

Resources

Looking for Admin?

Appeared in Searches

Latest Blog Posts

MCP directory API

Use `npx`

Use `~/.ssh/config`