Skip to main content
Glama
lms-ssh-client-mcp

lms-ssh-client-mcp

by Mr365truck

Model Context Protocol (MCP) SSH Client Server

An MCP server designed for LM Studio, Claude Desktop, and other MCP-enabled LLM hosts. This server enables LLMs to securely SSH into remote servers, execute commands, list directories, and manage files (read, write, delete, create directories, rename files) over SFTP.

Features

  • Persisted SSH Connections: Establish SSH sessions and maintain them in-memory, allowing consecutive tool calls on the same host without repeating credentials.

  • Remote Command Execution: Execute shell commands on the remote machine (ssh_execute_command).

  • Full SFTP File Manager:

    • List files and directories with formatted unix permissions, sizes, and timestamps (ssh_sftp_list_dir).

    • Read remote files up to 2MB securely (ssh_sftp_read_file).

    • Create, write, or update files (ssh_sftp_write_file).

    • Delete files (ssh_sftp_delete_file).

    • Create and delete directories (ssh_sftp_mkdir / ssh_sftp_rmdir).

    • Rename or move remote items (ssh_sftp_rename).

  • Flexible Authentication:

    • Authenticate using Username & Password.

    • Authenticate using private keys (either pass the raw key string or a local file path like ~/.ssh/id_rsa).

    • Zero-Config Fallback: If no credentials are specified, the server automatically looks for default keys in your local ~/.ssh/ directory (e.g. id_ed25519, id_rsa, id_ecdsa, etc.) to authenticate passwordlessly.

  • Graceful Shutdown: Automatically closes all active SSH connections when the LLM client stops the MCP server.


Related MCP server: ssh-mcp

Installation & Setup

  1. Clone and Install Dependencies: Navigate to the directory and run:

    npm install
  2. Build the Server: Compile the TypeScript files into JavaScript:

    npm run build

Configuring with LM Studio

There are two ways to load this MCP server in LM Studio:

Method 1: Edit the mcp.json Configuration File (Recommended)

You can directly add the configuration to your local LM Studio MCP configuration file (typically located at ~/.lmstudio/mcp.json on macOS/Linux).

  1. Open ~/.lmstudio/mcp.json in your favorite editor:

    nano ~/.lmstudio/mcp.json
  2. Add the server entry to the mcpServers object:

    {
      "mcpServers": {
        "lms-ssh-client-mcp": {
          "command": "node",
          "args": [
            "/Users/ethan/desktop/projects/lms-ssh-client-mcp/dist/index.js"
          ]
        }
      }
    }
  3. Save the file and restart LM Studio.

Method 2: Configure via the LM Studio UI

  1. Open LM Studio.

  2. Go to the Developer Tools tab (gear icon on the left sidebar / developer settings).

  3. Scroll down to the Model Context Protocol (MCP) section.

  4. Click Add Server and enter the following settings:

    • Name: lms-ssh-client-mcp

    • Type: stdio

    • Command: node

    • Arguments: ["/Users/ethan/desktop/projects/lms-ssh-client-mcp/dist/index.js"] (Make sure to use the absolute path to your compiled dist/index.js)

  5. Click Save to start the server.


Configuring with Claude Desktop

To use this server with Claude Desktop, add it to your claude_desktop_config.json (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ssh-client": {
      "command": "node",
      "args": ["/Users/ethan/desktop/projects/lms-ssh-client-mcp/dist/index.js"]
    }
  }
}

Tools Reference

The server exposes the following tools to the LLM:

1. ssh_connect

Connect to a remote server and get back a connectionId.

  • Arguments:

    • host (string, required): Hostname or IP address.

    • port (number, default: 22): Port number.

    • username (string, required): SSH username.

    • password (string, optional): SSH password.

    • privateKey (string, optional): Raw SSH private key text OR a path to the local key file (e.g., ~/.ssh/id_rsa).

    • passphrase (string, optional): Decryption passphrase for the private key if it is encrypted.

    • readyTimeout (number, default: 20000): Connection timeout in milliseconds.

2. ssh_execute_command

Execute shell commands on the remote machine.

  • Arguments:

    • connectionId (string, required): The ID returned by ssh_connect.

    • command (string, required): The shell command to run (e.g. cd /var/www && ls -la && tail -n 20 error.log).

    • timeoutMs (number, default: 30000): Command execution timeout.

NOTE

Environment state (like current working directorycd) is not preserved between individual ssh_execute_command tool calls. To perform multiple operations in the same folder or with the same variables, run them as a combined command using standard shell operators (e.g., cd /app && npm install && npm run build).

3. ssh_list_connections

Lists all active connections (shows connectionId, host, username, port, connectedAt).

  • Arguments: None.

4. ssh_close_connection

Terminate an active SSH connection cleanly.

  • Arguments:

    • connectionId (string, required): Connection to close.

5. ssh_sftp_list_dir

Inspect folders on the remote system using SFTP.

  • Arguments:

    • connectionId (string, required)

    • path (string, required): Remote path to inspect (e.g., /etc or .).

6. ssh_sftp_read_file

Read remote files securely.

  • Arguments:

    • connectionId (string, required)

    • path (string, required): File path to read.

    • encoding (string, default: "utf8"): Encoding of the content (use "base64" for binary files).

7. ssh_sftp_write_file

Write/upload files to the remote server.

  • Arguments:

    • connectionId (string, required)

    • path (string, required): File path to write.

    • content (string, required): File content text or base64-encoded binary.

    • encoding (string, default: "utf8")

8. ssh_sftp_delete_file

Delete files on the remote server.

  • Arguments:

    • connectionId (string, required)

    • path (string, required): File path to delete.

9. ssh_sftp_mkdir / ssh_sftp_rmdir

Create directories or delete empty directories.

  • Arguments:

    • connectionId (string, required)

    • path (string, required): Directory path.

10. ssh_sftp_rename

Rename or move a remote file or folder.

  • Arguments:

    • connectionId (string, required)

    • oldPath (string, required)

    • newPath (string, required)


Development & Debugging

Since stdio is used for MCP JSON-RPC communication, do not log to stdout (console.log) in your code as it will break the protocol parser. All log messages inside this server are written to stderr (console.error), which will appear in your LLM client's debug logs (e.g., in LM Studio's MCP log view).

Available Tools

11 tools
ssh_close_connectionB

Close an active SSH connection.

Inputs: connectionId (required).

ssh_connectA

Connect to a remote SSH server. Returns a session ID to be used for subsequent commands and files. If neither password nor privateKey are specified, this tool will attempt to use default keys in your ~/.ssh directory. If a file path is provided in privateKey, it will be loaded from disk.

Inputs: host (required), username (required), port, password, +4 more.

ssh_execute_commandA

Execute a command on the remote host via SSH. Note: Shell environment state like current directory (cd) is NOT preserved between distinct tool calls. To run multiple commands in the same path, chain them (e.g. 'cd /var/www && ls -la').

Inputs: connectionId (required), command (required), timeoutMs.

ssh_list_connectionsA

List all active SSH connection IDs and details.

Inputs: no named parameters.

ssh_sftp_delete_fileA

Delete a file on the remote server using SFTP.

Inputs: connectionId (required), path (required).

ssh_sftp_list_dirB

List files and directories on the remote server using SFTP.

Inputs: connectionId (required), path (required).

ssh_sftp_mkdirB

Create a directory on the remote server using SFTP.

Inputs: connectionId (required), path (required).

ssh_sftp_read_fileA

Read the contents of a file on the remote server using SFTP.

Inputs: connectionId (required), path (required), encoding.

ssh_sftp_renameA

Rename or move a file or directory on the remote server using SFTP.

Inputs: connectionId (required), oldPath (required), newPath (required).

ssh_sftp_rmdirB

Remove an empty directory on the remote server using SFTP.

Inputs: connectionId (required), path (required).

ssh_sftp_write_fileB

Write content to a file on the remote server using SFTP. Creates the file if it does not exist.

Inputs: connectionId (required), path (required), content (required), encoding.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: connection management, command execution, and SFTP operations are all separated. No two tools overlap in functionality, and descriptions clearly differentiate them.

    Naming Consistency5/5

    All tools follow a consistent 'ssh_' prefix for SSH operations and 'ssh_sftp_' for SFTP operations. Verbs are uniform (e.g., connect, execute, list, read, write), making the naming pattern predictable and easy to parse.

    Tool Count5/5

    With 11 tools, the set is well-scoped for an SSH client, covering connection lifecycles, command execution, and comprehensive SFTP file operations. Neither too few nor too many for the domain.

    Completeness5/5

    The tool set covers all essential SSH client operations: connect/disconnect, execute commands, and full SFTP CRUD (list, read, write, delete, rename, mkdir, rmdir). Minor gaps like directory uploads are compound operations, not necessary for basic coverage.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to securely connect to and manage remote servers via SSH, supporting command execution, file transfers via SFTP, and multi-server management with both password and SSH key authentication.
      9
      53 npm
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables LLMs to interact with remote servers via SSH, supporting command execution, file upload/download, and directory listing.
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to securely execute commands, transfer files, and manage port forwarding on remote servers via SSH.
      164 npm
      38
      Apache 2.0