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.