ssh-mcp-server

SSH-based MCP (Model Context Protocol) server that allows remote execution of SSH commands via the MCP protocol.

Project Overview

ssh-mcp-server enables AI assistants and applications supporting MCP protocol to execute remote SSH commands safely through a standardized interface.

Published as mcp-server-ssh-manager on NPM: https://www.npmjs.com/package/mcp-server-ssh-manager

Features

• Secure Connections: Supports password and private key authentication (with passphrase support)
• Multiple Private Keys: Supports trying multiple private key files in sequence - useful when unsure which key type (RSA, ED25519, etc.) the server accepts
• Host Key Verification: Flexible host key verification with auto-accept (default) or strict verification options
• Command Security Control: Command whitelist and blacklist mechanisms
• File Transfer: Bidirectional file uploads and downloads
• Ready to Use: Use via npx without installation

Usage

To use this MCP server, you don't need to install it globally. You can use it directly via npx in your configuration.

Available Tools

| Tool | Description | |---------|-----------| | set_current_server | Set the current SSH server for subsequent commands | | execute-command | Execute SSH commands on remote servers | | upload | Upload local files to remote servers | | download | Download files from remote servers | | get_current_server | Get current SSH server configuration and status |

MCP Configuration

Using with Cursor

Cursor supports MCP servers in two scopes:

1. Global Configuration (Available Across All Projects)

Edit the file ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-ssh-manager"
      ]
    }
  }
}

Alternatively, you can add via the UI:

1. Navigate to File → Preferences → Cursor Settings
2. Select "MCP"
3. Click "Add new global MCP server"

2. Project Configuration (Project-Specific)

Create or edit .cursor/mcp.json in your project directory:

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-ssh-manager"
      ]
    }
  }
}

Using with OpenCode

OpenCode uses a JSON configuration file at the project root level.

1. Using opencode.json (or opencode.jsonc)

Create or edit opencode.json in your project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ssh-mcp": {
      "enabled": true,
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-ssh-manager"
      ]
    }
  }
}

2. Using the CLI (Interactive)

Run the following command and follow the prompts:

opencode mcp add

Then:

• Enter MCP server name (e.g., ssh-mcp)
• Select MCP server type: Local
• Enter command to run: npx -y mcp-server-ssh-manager

Note: MCP servers add to your context in OpenCode, so be selective about which servers you enable to avoid exceeding context limits.

Tool Examples

Set current server (password authentication):

{
  "host": "192.168.1.100",
  "name": "production-server",
  "username": "admin",
  "password": "secret123",
  "port": 22
}

Set current server (private key authentication):

{
  "host": "192.168.1.100",
  "username": "admin",
  "privateKey": "/path/to/.ssh/id_rsa"
}

Set current server (multiple private keys):

{
  "host": "192.168.1.100",
  "username": "admin",
  "privateKey": [
    "/path/to/.ssh/id_rsa",
    "/path/to/.ssh/id_ed25519",
    "/path/to/.ssh/id_ecdsa"
  ]
}

ℹ️ Note: When providing multiple private keys, the server will try them in order until one succeeds. This is useful when you're unsure which key type the server accepts, or when you have keys for different authentication methods.

Set current server (encrypted private key with passphrase):

{
  "host": "192.168.1.100",
  "username": "admin",
  "privateKey": "/path/to/.ssh/id_rsa",
  "passphrase": "my-secret-passphrase"
}

Set current server (strict host key verification):

{
  "host": "192.168.1.100",
  "username": "admin",
  "privateKey": "/path/to/.ssh/id_rsa",
  "strictHostKeyChecking": true,
  "knownHosts": "/path/to/.ssh/known_hosts"
}

Authentication Methods:

By default, the server uses password authentication (defaults to admin/admin). You can also use:

• Private key authentication: Provide privateKey parameter (path to private key file)
  • Supports single key: "privateKey": "/path/to/.ssh/id_rsa"
  • Supports multiple keys (tried in sequence until one succeeds): "privateKey": ["/path/to/.ssh/id_rsa", "/path/to/.ssh/id_ed25519"]
  • This is useful when unsure which key type the server accepts (RSA, ED25519, ECDSA, etc.)
• Encrypted private key: Provide both privateKey and passphrase (note: only one passphrase is supported even with multiple keys - all encrypted keys must share the same passphrase, or use unencrypted keys)
• Host key verification:
  • Default: Auto-accept host keys (like SSH -o StrictHostKeyChecking=no)
  • Strict: Set strictHostKeyChecking: true and provide knownHosts file path

Execute command:

{
  "cmdString": "ls -la",
  "timeout": 5000
}

Upload file:

{
  "localPath": "/path/to/local/file.txt",
  "remotePath": "/remote/destination/file.txt"
}

Download file:

{
  "remotePath": "/remote/file.txt",
  "localPath": "/local/destination/file.txt"
}

Get current server:

{}

Development

If you want to contribute to this project or run it from source:

# Clone the repository
git clone https://github.com/yourusername/ssh-mcp-server.git
cd ssh-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

To run from source instead of NPM, change your configuration to point to the build output:

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "node",
      "args": [
        "/path/to/ssh-mcp-server/build/index.js"
      ]
    }
  }
}