mcp-ssh-server

dave-nathaniel/mcp-ssh-server

3.1

If you are the rightful owner of mcp-ssh-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The MCP SSH Server is a comprehensive Model Context Protocol server that facilitates SSH connections and command execution on remote servers, leveraging FastMCP for protocol implementation.

Tools
10
Resources
0
Prompts
0

MCP SSH Server

A full-fledged Model Context Protocol (MCP) server that enables SSH connections and command execution on remote servers. This server implements all standard MCP protocols using FastMCP and provides a robust interface for managing SSH connections.

Features

  • Full MCP Protocol Support: Implements all standard MCP protocols including tools, resources, and prompts using FastMCP
  • SSH Connection Management: Connect to multiple remote servers simultaneously with connection pooling
  • Command Execution: Execute commands on remote servers with real-time output and interactive command support
  • File Operations: Upload, download, list, delete, and create files/directories on remote servers
  • Connection Pooling: Efficient management of multiple SSH connections with configurable limits
  • Security: Support for password, key-based, and interactive authentication
  • Logging: Comprehensive structured logging with configurable levels
  • Error Handling: Robust error handling and recovery mechanisms
  • Async Support: Full async/await support for all operations

Demo

Installation

Prerequisites

  • Python 3.10 or higher
  • uv package manager (recommended) or pip

Install Dependencies

# Using uv (recommended)
uv sync

# Using pip
pip install -e .

Build

Building with uv

# Build the package
uv build

# This creates a wheel file in dist/ directory
# Example: dist/mcp_ssh_server-1.0.0-py3-none-any.whl

Installing the Built Package

# Install from the built wheel
pip install dist/mcp_ssh_server-1.0.0-py3-none-any.whl

# Or install from the current directory
pip install -e .

Running the Built Package

# Run the MCP server in stdio mode (for Claude Desktop, mcp dev, etc.)
python -m mcp_ssh_server

# Or using the helper script for inspectors / installers
mcp dev server.py

# Or using the installed script
mcp-ssh-server

Usage

Basic Usage

# Run the MCP server in stdio mode (for Claude Desktop, mcp dev, etc.)
python -m mcp_ssh_server

# Or using the helper script for inspectors / installers
mcp dev server.py

# Or using the installed script
mcp-ssh-server

Configuration

Create a configuration file config.json in the project directory:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "log_level": "INFO"
  },
  "ssh": {
    "default_timeout": 30,
    "max_connections": 10,
    "connection_pool_size": 5
  }
}

MCP Protocol Support

This server implements the following MCP protocols using FastMCP:

Tools

  • ssh_connect: Establish SSH connection to a remote server
  • ssh_execute: Execute commands on remote servers
  • ssh_execute_interactive: Execute multiple commands interactively
  • ssh_upload: Upload files to remote servers
  • ssh_download: Download files from remote servers
  • ssh_list_files: List files and directories on remote servers
  • ssh_delete_file: Delete files on remote servers
  • ssh_create_directory: Create directories on remote servers
  • ssh_disconnect: Close SSH connections
  • ssh_list_connections: List active SSH connections

Resources

  • ssh://connections: Resource providing list of active SSH connections

Prompts

  • ssh_command_prompt: Interactive prompt for SSH command execution
  • ssh_file_operation_prompt: Interactive prompt for file operations

API Reference

SSH Connection

# Connect to a remote server
{
  "method": "tools/call",
  "params": {
    "name": "ssh_connect",
    "arguments": {
      "host": "example.com",
      "port": 22,
      "username": "user",
      "password": "password",
      "connection_id": "conn1",
      "timeout": 30
    }
  }
}

Command Execution

# Execute a command on remote server
{
  "method": "tools/call",
  "params": {
    "name": "ssh_execute",
    "arguments": {
      "connection_id": "conn1",
      "command": "ls -la",
      "timeout": 30
    }
  }
}

Interactive Command Execution

# Execute multiple commands interactively
{
  "method": "tools/call",
  "params": {
    "name": "ssh_execute_interactive",
    "arguments": {
      "connection_id": "conn1",
      "commands": ["cd /tmp", "ls -la", "pwd"],
      "timeout": 30
    }
  }
}

File Operations

# Upload a file
{
  "method": "tools/call",
  "params": {
    "name": "ssh_upload",
    "arguments": {
      "connection_id": "conn1",
      "local_path": "/path/to/local/file.txt",
      "remote_path": "/remote/path/file.txt"
    }
  }
}

# Download a file
{
  "method": "tools/call",
  "params": {
    "name": "ssh_download",
    "arguments": {
      "connection_id": "conn1",
      "remote_path": "/remote/path/file.txt",
      "local_path": "/path/to/local/file.txt"
    }
  }
}

# List files
{
  "method": "tools/call",
  "params": {
    "name": "ssh_list_files",
    "arguments": {
      "connection_id": "conn1",
      "remote_path": "/tmp"
    }
  }
}

Development

Setup Development Environment

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

Testing

Run the test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=mcp_ssh_server --cov-report=term-missing --cov-report=html

# Run specific test file
pytest tests/test_ssh_manager.py

# Test server initialization
python test_server.py

Technical Details

FastMCP Implementation

This server uses FastMCP for a modern, streamlined MCP implementation:

  • All tools are implemented as async functions using @mcp.tool() decorators
  • Resources are implemented using @mcp.resource() decorators
  • Prompts are implemented using @mcp.prompt() decorators
  • Proper async/await handling throughout the codebase
  • No blocking operations in tool handlers

SSH Manager

The SSH manager provides:

  • Connection pooling with configurable limits
  • Automatic connection cleanup
  • Support for multiple authentication methods
  • Comprehensive error handling and logging
  • Async operations for all SSH interactions

Error Handling

  • All operations return structured error responses
  • Comprehensive logging for debugging
  • Graceful handling of connection failures
  • Timeout protection for all operations

Security Considerations

  • Passwords are handled securely and not logged
  • SSH keys are stored securely
  • Connection timeouts prevent hanging connections
  • Input validation prevents command injection
  • All operations are logged for audit purposes
  • Async operations prevent blocking the event loop

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Run the test suite
  6. Submit a pull request

Support

For issues and questions, please open an issue on the GitHub repository.