my-mcp-ssh

A Model Context Protocol (MCP) based SSH connection tool that allows large language models to securely connect to remote servers via SSH and perform file operations through the MCP protocol.

Features

• SSH Connection Management: Connect to remote SSH servers
• Command Execution: Execute commands on remote servers
• File Transfer: Upload and download files
• Session Management: Maintain and close SSH sessions

Installation

Dependencies

• Python >= 3.12
• uv package manager

# Clone the project
git clone https://github.com/ffpy/my-mcp-ssh.git

# Enter the project directory
cd my-mcp-ssh

# Install dependencies
uv sync

Usage

Configure in client

{
  "mcpServers": {
    "my-mcp-ssh": {
      "command": "uv",
      "args": [
        "--directory",
        "<your_path>/my-mcp-ssh",
        "run",
        "src/main.py"
      ],
      "env": {}
    }
  }
}

Environment Variables

SSH Connection Defaults (Optional)

Environment variables provide default values for SSH connections, useful when frequently connecting to the same server or in automated environments:

• SSH_HOST: SSH server hostname or IP address
• SSH_PORT: SSH server port
• SSH_USERNAME: SSH username
• SSH_PASSWORD: SSH password (if using password authentication)
• SSH_KEY_PATH: SSH private key file path (if using key authentication)
• SSH_KEY_PASSPHRASE: SSH private key passphrase (if needed)

When to use SSH environment variables:

• Repeated connections: When connecting to the same server multiple times
• CI/CD pipelines: For automated deployment scripts
• Development environments: Set defaults for your commonly used servers
• Container deployments: Configure defaults without modifying code

Note: Parameters passed to the connect tool always override environment variables.

Server Configuration

Additional server behavior can be configured:

• SESSION_TIMEOUT: Session timeout in minutes, default is 30 minutes
• MAX_OUTPUT_LENGTH: Maximum command output length in characters, default is 5000 characters

SSH Credentials File

For better security, you can store SSH credentials in a local configuration file instead of passing passwords as parameters.

1. Copy the example file:

cp ssh-credentials.json.example ssh-credentials.json

2. Edit ssh-credentials.json with your actual credentials:

{
  "root@192.168.1.100": "your_password",
  "admin@web-[0-9].example.com": "web_password",
  "deploy@server-{dev,test,staging}.company.com": "deploy_password",
  "admin@*.internal.network": "internal_password"
}

Supported Patterns:

• * - matches any characters
• ? - matches single character
• [0-9] - matches any digit
• {dev,test,staging} - matches any of the listed options

Authentication Priority Order:

1. Parameters passed to connect tool (password, key_path)
2. Exact match in credentials file (username@host)
3. Pattern match in credentials file (wildcards)
4. Environment variable password (SSH_PASSWORD)
5. Environment variable key (SSH_KEY_PATH)
6. Default SSH key (~/.ssh/id_rsa if exists)

Security:

• File permissions are automatically set to 600 (owner read/write only)
• The file is added to .gitignore to prevent accidental commits

Note:

• Credential file changes take effect immediately without server restart
• The file is read fresh on each connection attempt

Tool List

connect

Connect to an SSH server

Parameters:

• host: SSH server hostname or IP address (optional)
• port: SSH server port (optional, default 22)
• username: SSH username (optional)
• password: SSH password for authentication (optional)
• key_path: SSH private key file path for authentication (optional)
• key_passphrase: SSH private key passphrase if needed (optional)

disconnect

Disconnect from an SSH session

Parameters:

• session_id: The session ID to disconnect

list_sessions

List all active SSH sessions

Parameters:

• None

execute

Execute a command on the SSH server

Parameters:

• session_id: Session ID
• command: Command to execute
• stdin: Input string to provide to the command, default is empty
• timeout: Command timeout in seconds, default is 60 seconds

upload

Upload a file to the SSH server

Parameters:

• session_id: Session ID
• local_path: Local file path
• remote_path: Remote file path

download

Download a file from the SSH server

Parameters:

• session_id: Session ID
• remote_path: Remote file path
• local_path: Local file path

Debugging

Run ./inspector.sh for online debugging

License

my-mcp-ssh is licensed under the Apache License, Version 2.0