Skip to main content
Glama
Xiyueyy

ssh-mcp-server

by Xiyueyy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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

Links

Related MCP server: R-Shell

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:

  1. Directly provide --admin-ids

  2. 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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Simple SSH MCP Server

    bhayanak
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives AI assistants full SSH/SFTP remote operations — session management, command execution, interactive shells, file transfers, port forwarding, and system diagnostics.
    2
    MIT

  • R-Shell

    MageGojo
    A
    license
    Not graded
    quality
    A
    maintenance
    MCP server enabling AI assistants to securely operate remote servers via persistent SSH sessions, with tools for command execution, file transfer, directory listing, and system monitoring.
    4
    MIT

  • SSH MCP Server

    avranju
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives AI agents SSH capabilities to execute commands, transfer files, and inspect remote systems through a preconfigured host list.
    51 npm
    MIT

  • open-ssh-mcp

    cjp1016
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server for managing remote SSH servers, enabling AI agents to execute commands, transfer files, and perform deployment operations securely.
    MIT

Appeared in Searches