SSH MCP Server

A Model Context Protocol (MCP) server that provides SSH functionality including file copying between servers, command execution, and file management.

Features

🔐 SSH Connection Management: Connect to multiple SSH servers with connection pooling
📁 File Operations: Copy files between local and remote servers, or between remote servers
🖥️ Command Execution: Execute commands on remote servers
📋 File Listing: List files and directories on local or remote systems
ℹ️ File Information: Get detailed file information (size, permissions, timestamps)
🔑 Authentication: Support for password and private key authentication

Installation

npm install
npm run build

Usage

Claude Desktop Integration

To use this SSH MCP server with Claude Desktop, you need to configure it in your Claude Desktop settings.

1. Build the Server

npm install
npm run build

2. Configure Claude Desktop

Add the following configuration to your Claude Desktop MCP settings file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Important: Replace /absolute/path/to/mcp-ssh/ with the actual absolute path to your mcp-ssh project directory.

3. Restart Claude Desktop

After adding the configuration, restart Claude Desktop completely for the changes to take effect.

4. Verify Installation

Once restarted, you should see the SSH tools available in Claude Desktop. You can test by asking Claude to:

"Connect to an SSH server"
"List available SSH tools"
"Copy a file between servers"

Development Mode

npm run dev

Production

npm run build
npm start

Quick Start

New to SSH MCP Server? Check out our How to Use Authentication Guide for simple, step-by-step instructions on connecting to your servers using natural language with Claude Desktop.

Available Tools

1. ssh_connect

Connect to an SSH server.

Parameters:

host (string): SSH server hostname or IP address
port (number, default: 22): SSH port number
username (string): SSH username
password (string, optional): SSH password
privateKeyPath (string, optional): Path to private key file
passphrase (string, optional): Passphrase for private key
connectionId (string): Unique identifier for this connection

Authentication Methods:

Password Authentication:

{
  "host": "192.168.1.100",
  "username": "your_username",
  "password": "your_password",
  "connectionId": "server1"
}

SSH Key Authentication:

{
  "host": "192.168.1.100",
  "username": "your_username",
  "privateKeyPath": "/path/to/private/key",
  "passphrase": "optional_passphrase",
  "connectionId": "server1"
}

2. ssh_disconnect

Disconnect from an SSH server.

Parameters:

connectionId (string): Connection ID to disconnect

3. ssh_execute

Execute a command on a remote SSH server.

Parameters:

connectionId (string): SSH connection ID
command (string): Command to execute
cwd (string, optional): Working directory for command execution

Example:

{
  "connectionId": "server1",
  "command": "ls -la /home/user",
  "cwd": "/home/user"
}

4. ssh_copy_file

Copy files between local and remote servers or between remote servers.

Parameters:

sourceConnectionId (string): Source SSH connection ID (use "local" for local files)
sourcePath (string): Source file path
targetConnectionId (string): Target SSH connection ID (use "local" for local files)
targetPath (string): Target file path
createDirectories (boolean, default: true): Create target directories if they don't exist

Examples:

Local to Remote:

{
  "sourceConnectionId": "local",
  "sourcePath": "/local/file.txt",
  "targetConnectionId": "server1",
  "targetPath": "/remote/file.txt"
}

Remote to Local:

{
  "sourceConnectionId": "server1",
  "sourcePath": "/remote/file.txt",
  "targetConnectionId": "local",
  "targetPath": "/local/file.txt"
}

Remote to Remote:

{
  "sourceConnectionId": "server1",
  "sourcePath": "/path/on/server1/file.txt",
  "targetConnectionId": "server2",
  "targetPath": "/path/on/server2/file.txt"
}

5. ssh_list_files

List files and directories on local or remote server.

Parameters:

connectionId (string): SSH connection ID (use "local" for local files)
remotePath (string): Directory path to list
showHidden (boolean, default: false): Show hidden files

6. ssh_file_info

Get file information (size, permissions, etc.).

Parameters:

connectionId (string): SSH connection ID (use "local" for local files)
filePath (string): File path to get info for

Troubleshooting

Claude Desktop Integration Issues

Server not appearing in Claude Desktop:

Verify the absolute path in claude_desktop_config.json is correct
Ensure the server was built successfully (npm run build)
Check that dist/index.js exists in your project directory
Restart Claude Desktop completely (quit and reopen)
Check Claude Desktop logs for error messages

Permission errors:

Ensure Node.js has permission to read the project directory
On macOS, you may need to grant Claude Desktop full disk access in System Preferences > Security & Privacy

SSH connection failures:

Verify SSH server is accessible from your machine
Test SSH connection manually: ssh username@hostname
Check SSH key permissions (should be 600): chmod 600 ~/.ssh/id_rsa
Ensure SSH key is in the correct format (OpenSSH)

File transfer issues:

Check file paths are absolute and correct
Verify write permissions on target directories
Ensure sufficient disk space on target system

Getting Help

If you encounter issues:

Check the Claude Desktop console/logs for error messages
Verify your configuration matches the examples exactly
Test SSH connections manually before using the MCP server

Security Considerations

Private keys should be stored securely with appropriate file permissions (600)
Use SSH key authentication instead of passwords when possible
Consider using SSH agent forwarding for additional security
The server maintains connection pools - ensure proper cleanup on shutdown

Error Handling

The server provides detailed error messages for:

Connection failures
Authentication errors
File operation errors
Invalid parameters
Missing connections

Connection Management

Connections are pooled and reused for efficiency
Each connection has a unique ID for reference
Connections are automatically cleaned up on server shutdown
Use ssh_disconnect to manually close connections

Temporary Files

For remote-to-remote file transfers, temporary files are created in /tmp/ and automatically cleaned up after transfer completion or on error.

Dependencies

@modelcontextprotocol/sdk: MCP SDK for server implementation
node-ssh: SSH client for Node.js
ssh2: Low-level SSH2 client
zod: Runtime type validation

License

MIT

SSH MCP Server

A Model Context Protocol (MCP) server that provides SSH functionality including file copying between servers, command execution, and file management.

Features

🔐 SSH Connection Management: Connect to multiple SSH servers with connection pooling
📁 File Operations: Copy files between local and remote servers, or between remote servers
🖥️ Command Execution: Execute commands on remote servers
📋 File Listing: List files and directories on local or remote systems
ℹ️ File Information: Get detailed file information (size, permissions, timestamps)
🔑 Authentication: Support for password and private key authentication

Installation

npm install
npm run build

Usage

Claude Desktop Integration

To use this SSH MCP server with Claude Desktop, you need to configure it in your Claude Desktop settings.

1. Build the Server

npm install
npm run build

2. Configure Claude Desktop

Add the following configuration to your Claude Desktop MCP settings file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Important: Replace /absolute/path/to/mcp-ssh/ with the actual absolute path to your mcp-ssh project directory.

3. Restart Claude Desktop

After adding the configuration, restart Claude Desktop completely for the changes to take effect.

4. Verify Installation

Once restarted, you should see the SSH tools available in Claude Desktop. You can test by asking Claude to:

"Connect to an SSH server"
"List available SSH tools"
"Copy a file between servers"

Development Mode

npm run dev

Production

npm run build
npm start

Quick Start

New to SSH MCP Server? Check out our How to Use Authentication Guide for simple, step-by-step instructions on connecting to your servers using natural language with Claude Desktop.

Available Tools

1. ssh_connect

Connect to an SSH server.

Parameters:

host (string): SSH server hostname or IP address
port (number, default: 22): SSH port number
username (string): SSH username
password (string, optional): SSH password
privateKeyPath (string, optional): Path to private key file
passphrase (string, optional): Passphrase for private key
connectionId (string): Unique identifier for this connection

Authentication Methods:

Password Authentication:

{
  "host": "192.168.1.100",
  "username": "your_username",
  "password": "your_password",
  "connectionId": "server1"
}

SSH Key Authentication:

{
  "host": "192.168.1.100",
  "username": "your_username",
  "privateKeyPath": "/path/to/private/key",
  "passphrase": "optional_passphrase",
  "connectionId": "server1"
}

2. ssh_disconnect

Disconnect from an SSH server.

Parameters:

connectionId (string): Connection ID to disconnect

3. ssh_execute

Execute a command on a remote SSH server.

Parameters:

connectionId (string): SSH connection ID
command (string): Command to execute
cwd (string, optional): Working directory for command execution

Example:

{
  "connectionId": "server1",
  "command": "ls -la /home/user",
  "cwd": "/home/user"
}

4. ssh_copy_file

Copy files between local and remote servers or between remote servers.

Parameters:

sourceConnectionId (string): Source SSH connection ID (use "local" for local files)
sourcePath (string): Source file path
targetConnectionId (string): Target SSH connection ID (use "local" for local files)
targetPath (string): Target file path
createDirectories (boolean, default: true): Create target directories if they don't exist

Examples:

Local to Remote:

{
  "sourceConnectionId": "local",
  "sourcePath": "/local/file.txt",
  "targetConnectionId": "server1",
  "targetPath": "/remote/file.txt"
}

Remote to Local:

{
  "sourceConnectionId": "server1",
  "sourcePath": "/remote/file.txt",
  "targetConnectionId": "local",
  "targetPath": "/local/file.txt"
}

Remote to Remote:

{
  "sourceConnectionId": "server1",
  "sourcePath": "/path/on/server1/file.txt",
  "targetConnectionId": "server2",
  "targetPath": "/path/on/server2/file.txt"
}

5. ssh_list_files

List files and directories on local or remote server.

Parameters:

connectionId (string): SSH connection ID (use "local" for local files)
remotePath (string): Directory path to list
showHidden (boolean, default: false): Show hidden files

6. ssh_file_info

Get file information (size, permissions, etc.).

Parameters:

connectionId (string): SSH connection ID (use "local" for local files)
filePath (string): File path to get info for

Troubleshooting

Claude Desktop Integration Issues

Server not appearing in Claude Desktop:

Verify the absolute path in claude_desktop_config.json is correct
Ensure the server was built successfully (npm run build)
Check that dist/index.js exists in your project directory
Restart Claude Desktop completely (quit and reopen)
Check Claude Desktop logs for error messages

Permission errors:

Ensure Node.js has permission to read the project directory
On macOS, you may need to grant Claude Desktop full disk access in System Preferences > Security & Privacy

SSH connection failures:

Verify SSH server is accessible from your machine
Test SSH connection manually: ssh username@hostname
Check SSH key permissions (should be 600): chmod 600 ~/.ssh/id_rsa
Ensure SSH key is in the correct format (OpenSSH)

File transfer issues:

Check file paths are absolute and correct
Verify write permissions on target directories
Ensure sufficient disk space on target system

Getting Help

If you encounter issues:

Check the Claude Desktop console/logs for error messages
Verify your configuration matches the examples exactly
Test SSH connections manually before using the MCP server

Security Considerations

Private keys should be stored securely with appropriate file permissions (600)
Use SSH key authentication instead of passwords when possible
Consider using SSH agent forwarding for additional security
The server maintains connection pools - ensure proper cleanup on shutdown

Error Handling

The server provides detailed error messages for:

Connection failures
Authentication errors
File operation errors
Invalid parameters
Missing connections

Connection Management

Connections are pooled and reused for efficiency
Each connection has a unique ID for reference
Connections are automatically cleaned up on server shutdown
Use ssh_disconnect to manually close connections

Temporary Files

For remote-to-remote file transfers, temporary files are created in /tmp/ and automatically cleaned up after transfer completion or on error.

Dependencies

@modelcontextprotocol/sdk: MCP SDK for server implementation
node-ssh: SSH client for Node.js
ssh2: Low-level SSH2 client
zod: Runtime type validation

License

MIT