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

Related MCP server: Terminal MCP Server

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