mcp-server-ssh-exec 0.1.0

Execute commands remotely through an ssh connection

mcp-server-ssh-exec

** All of the code in this project was created by a generative AI. **

An MCP server for SSH connections and file operations.

Components

Tools

The server implements several SSH-related tools:

• connect: Connect to an SSH server

  • Optional parameters to override environment variables: host, port, username, password, key_path, key_passphrase
  • Returns connection status

• disconnect: Disconnect from the SSH server

  • No parameters required
  • Returns disconnection status

• execute: Execute a command on the SSH server

  • Required parameter: command (string)
  • Optional parameter: timeout (integer, seconds, default: 60)
  • Returns command output (stdout and stderr) and exit status

• upload: Upload a file to the SSH server

  • Required parameters: local_path, remote_path
  • Returns upload status

• download: Download a file from the SSH server

  • Required parameters: remote_path, local_path
  • Returns download status

• list_files: List files in a directory on the SSH server

  • Required parameter: path
  • Returns list of files with type and size information

Configuration

The SSH connection parameters can be configured using environment variables in the MCP settings:

• SSH_HOST: SSH server hostname or IP address
• SSH_PORT: SSH server port (default: 22)
• SSH_USERNAME: SSH username
• SSH_PASSWORD: SSH password (if using password authentication)
• SSH_KEY_PATH: Path to SSH private key file (if using key authentication)
• SSH_KEY_PASSPHRASE: Passphrase for SSH private key (if required)

You must provide either SSH_PASSWORD or SSH_KEY_PATH for authentication.

Example Configuration

An example MCP configuration file is provided in mcp-config-example.json. You can use this as a template for configuring the SSH MCP server:

{
  "mcpServers": {
    "mcp-server-ssh-exec": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-ssh-exec",
        "run",
        "mcp-server-ssh-exec"
      ],
      "env": {
        "SSH_HOST": "example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "username",
        "SSH_PASSWORD": "password",
        "SSH_KEY_PATH": "/path/to/private_key",
        "SSH_KEY_PASSPHRASE": "key_passphrase"
      }
    }
  }
}

Note: You typically only need to provide either SSH_PASSWORD or SSH_KEY_PATH (with optional SSH_KEY_PASSPHRASE), not both.

Examples

An example Python script is provided in the examples directory to demonstrate how to use the SSH MCP server:

• ssh_example.py: Shows how to connect to an SSH server, execute commands, upload/download files, list directory contents, and disconnect.

To run the example:

python examples/ssh_example.py

This example assumes the SSH MCP server is already configured and running.

Using with Cline

To help Cline understand how to use the SSH MCP server without reading the README.md file, the following files are provided:

• cline_ssh_usage_example.md: A quick reference guide for using the SSH MCP server with Cline, including example commands and a complete workflow.
• create_test_file.py: A script to create a test file for upload/download testing.
• test_ssh_mcp.sh: A shell script that creates a test file and provides step-by-step instructions for testing the SSH MCP server with Cline.
• test_ssh_mcp.py: A Python script that demonstrates how to use the SSH MCP server directly from Python, without using Cline.
• ssh_mcp_guide.html: An HTML guide with examples and a complete workflow for using the SSH MCP server with Cline.

To test the SSH MCP server with Cline:

./test_ssh_mcp.sh

This will create a test file and display instructions for testing the SSH MCP server with Cline.

To test the SSH MCP server directly from Python:

./test_ssh_mcp.py

This will perform a complete test of the SSH MCP server, including connecting, executing commands, uploading/downloading files, and disconnecting.

Quickstart

Install

All-in-One Setup

For a complete setup and test of the SSH MCP server, you can use the all-in-one setup script:

./setup_and_test.sh

This script will:

1. Install the required dependencies
2. Install the SSH MCP server in Cline or Claude Desktop (or both)
3. Test the SSH MCP server

Manual Setup

Dependencies

Before using the SSH MCP server, you need to install the required dependencies:

./install_dependencies.sh

This script will install the paramiko Python package, which is required for SSH connections.

Automatic Installation

Two Python scripts are provided to automatically install the SSH MCP server:

1. For Cline:

./install_ssh_mcp.py

2. For Claude Desktop:

./install_ssh_mcp_claude.py

These scripts will:

1. Detect the location of the configuration file
2. Prompt you for SSH connection parameters
3. Update the configuration file with the SSH MCP server configuration

Manual Installation

Claude Desktop

An example Claude Desktop configuration file is provided in claude-desktop-config-example.json. This shows how to configure the SSH MCP server in Claude Desktop.

To install the SSH MCP server in Claude Desktop:

1. Locate your Claude Desktop configuration file:

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

2. Add the SSH MCP server configuration to the mcpServers object in the configuration file:

{
  "mcpServers": {
    "mcp-server-ssh-exec": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-ssh-exec",
        "run",
        "mcp-server-ssh-exec"
      ],
      "env": {
        "SSH_HOST": "example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "username",
        "SSH_PASSWORD": "password",
        "SSH_KEY_PATH": "/path/to/private_key",
        "SSH_KEY_PASSPHRASE": "key_passphrase"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

3. Restart Claude Desktop to apply the changes.

Note: Make sure to replace the placeholder values with your actual SSH connection details.

Development

Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:

uv sync

2. Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

• Token: --token or UV_PUBLISH_TOKEN
• Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Testing

A test script is provided in the tests directory to verify that the SSH MCP server is working correctly:

python tests/test_ssh_connect.py

This test script uses unittest and mocking to test the basic functionality of the SSH MCP server without actually connecting to an SSH server.

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-server-ssh-exec run mcp-server-ssh-exec

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.