SSH MCP Server

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

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

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

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

Production

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:

1. Password Authentication:

2. SSH Key Authentication:

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:

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:

Remote to Local:

Remote to Remote:

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:

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

Permission errors:

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

SSH connection failures:

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

File transfer issues:

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

Getting Help

If you encounter issues:

1. Check the Claude Desktop console/logs for error messages
2. Verify your configuration matches the examples exactly
3. 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