FastMCP SSH Server - Python Implementation

🚀 A modern, FastMCP-based SSH server implementation for Model Context Protocol (MCP)

FastMCP SSH Server is a Python implementation of an SSH server for the Model Context Protocol, providing seamless SSH connection management and command execution capabilities for AI models. This is a complete re-implementation of the TypeScript version with enhanced features and improved performance.

✨ Features

🔌 Core Capabilities

Multi-SSH Connection Management: Connect to multiple SSH servers simultaneously
FastMCP Integration: Native integration with FastMCP framework for optimal performance
Authentication Methods: Support for password and private key authentication
Security Validation: Command whitelist/blacklist with regex pattern matching
File Transfer: Secure SFTP upload and download operations
Async Architecture: Full async/await support for high performance

🛡️ Security Features

Command Filtering: Configurable whitelist and blacklist for command security
Connection Validation: Comprehensive SSH connection parameter validation
Error Handling: Robust error handling with detailed logging
Secure Credentials: Support for private key authentication with passphrase protection

🚀 Performance & Reliability

Connection Pooling: Efficient connection reuse and management
Singleton Pattern: Centralized connection management
Timeout Controls: Configurable timeouts for all operations
Resource Cleanup: Automatic cleanup of connections and resources

📦 Installation

Requirements

Python 3.12+ (recommended)
uv package manager (recommended) or pip
AsyncSSH for SSH connections
FastMCP framework

Using uv (Recommended)

# Install from source
git clone https://github.com/your-username/fastmcp-ssh-server.git
cd fastmcp-ssh-server

# Install with uv
uv sync

# Or install in development mode
uv sync --dev

Using pip

# Install from source
git clone https://github.com/your-username/fastmcp-ssh-server.git
cd fastmcp-ssh-server

# Install dependencies
pip install -e .

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

From PyPI (Future)

# Will be available when published
pip install fastmcp-ssh-server

🚀 Quick Start

1. Basic Usage

# Single connection mode
fastmcp-ssh-server --host example.com --username myuser --password mypass

# Multiple connection mode using SSH connection strings
fastmcp-ssh-server user1@server1.com:22 user2@server2.com:2222

# With private key authentication
fastmcp-ssh-server --host server.com --username user --private-key ~/.ssh/id_rsa

2. Security Configuration

# With command restrictions
fastmcp-ssh-server \
    --host example.com \
    --username user \
    --password pass \
    --whitelist "ls,pwd,echo.*" \
    --blacklist "rm.*,sudo.*"

3. Configuration File (Coming Soon)

# config.yaml
servers:
  production:
    host: prod.example.com
    port: 22
    username: deploy
    private_key: ~/.ssh/prod_key
    whitelist: ["git.*", "npm.*", "node.*"]
    blacklist: ["rm.*", "sudo.*"]

  staging:
    host: staging.example.com
    port: 2222
    username: dev
    password: dev_password
    whitelist: ["*"]
    blacklist: ["rm -rf"]

📖 Usage Guide

Command Line Interface

The FastMCP SSH Server provides a flexible CLI with support for both single and multiple connection modes.

Single Connection Mode

fastmcp-ssh-server [OPTIONS]

Options:
  -h, --host TEXT          SSH hostname
  -p, --port INTEGER       SSH port (default: 22)
  -u, --username TEXT      SSH username
  -w, --password TEXT      SSH password
  -k, --private-key TEXT   SSH private key file path
  -P, --passphrase TEXT    SSH private key passphrase
  -W, --whitelist TEXT     Command whitelist patterns (comma-separated)
  -B, --blacklist TEXT     Command blacklist patterns (comma-separated)
  --help                   Show help and exit

Multiple Connection Mode

# Format: [user@]host[:port]
fastmcp-ssh-server user1@server1.com:22 user2@server2.com:2222

Global Security Options

# Apply security settings to all connections
fastmcp-ssh-server --whitelist "ls,pwd,cat" --blacklist "rm,sudo" \
    user1@server1.com user2@server2.com

MCP Tools

The server provides four main MCP tools:

1. `execute-command`

Execute commands on SSH servers with security validation.

{
  "tool": "execute-command",
  "arguments": {
    "cmdString": "ls -la /home",
    "serverName": "production",
    "timeout": 30
  }
}

2. `upload`

Upload files to SSH servers via SFTP.

{
  "tool": "upload",
  "arguments": {
    "localPath": "/local/file.txt",
    "remotePath": "/remote/path/file.txt",
    "serverName": "production"
  }
}

3. `download`

Download files from SSH servers via SFTP.

{
  "tool": "download",
  "arguments": {
    "remotePath": "/remote/path/file.txt",
    "localPath": "/local/file.txt",
    "serverName": "production"
  }
}

4. `list-servers`

List all configured SSH servers and their status.

{
  "tool": "list-servers",
  "arguments": {}
}

🔧 Configuration

Security Configuration

Command Whitelist

Use regex patterns to allow specific commands
["ls.*", "echo.*", "pwd"] - Allow ls, echo commands and pwd
["*"] - Allow all commands (use with blacklist)

Command Blacklist

Use regex patterns to deny specific commands
["rm.*", "sudo.*"] - Deny rm and sudo commands
[".*--force.*"] - Deny any command with --force flag

Example Security Configurations

# Development environment - restrictive
--whitelist "git.*,npm.*,node.*,python.*" \
--blacklist ".*--force.*,rm.*"

# Production environment - very restrictive
--whitelist "ls,pwd,cat,grep" \
--blacklist "rm.*,sudo.*,chmod.*"

# Staging environment - moderate
--whitelist "*" \
--blacklist "rm -rf.*,sudo su.*,dd.*"

Authentication Methods

Password Authentication

fastmcp-ssh-server --host server.com --username user --password secret

Private Key Authentication

# Without passphrase
fastmcp-ssh-server --host server.com --username user --private-key ~/.ssh/id_rsa

# With passphrase
fastmcp-ssh-server --host server.com --username user \
    --private-key ~/.ssh/id_rsa --passphrase mypassphrase

Mixed Authentication for Multiple Servers

# Use global password for connection strings without explicit auth
fastmcp-ssh-server --password globalpass \
    user1@server1.com \
    user2@server2.com

🧪 Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/your-username/fastmcp-ssh-server.git
cd fastmcp-ssh-server

# Install with development dependencies
uv sync --dev

# Or with pip
pip install -e ".[dev]"

Running Tests

# Run all tests with coverage
python tests/run_tests.py

# Run specific test categories
python tests/run_tests.py --unit          # Unit tests only
python tests/run_tests.py --integration   # Integration tests only
python tests/run_tests.py --fast          # Fast tests only

# Run with verbose output
python tests/run_tests.py --verbose

# Generate coverage report
python tests/run_tests.py --coverage

Code Quality

# Run linting and formatting
python tests/run_tests.py --lint

# Or run tools individually
ruff check src/
black src/
isort src/
mypy src/

Project Structure

fastmcp-ssh-server/
├── src/
│   └── python_ssh_mcp/
│       ├── __init__.py          # Package initialization
│       ├── __main__.py          # Module entry point
│       ├── main.py              # Main application entry
│       ├── server.py            # SSH MCP server implementation
│       ├── ssh_manager.py       # SSH connection manager
│       ├── cli.py               # Command line interface
│       ├── models.py            # Pydantic data models
│       ├── tools/               # MCP tools implementation
│       │   ├── __init__.py
│       │   ├── execute_command.py
│       │   ├── upload.py
│       │   ├── download.py
│       │   └── list_servers.py
│       └── utils/               # Utility modules
│           ├── __init__.py
│           ├── logger.py        # Logging system
│           └── error_handling.py
├── tests/                       # Test suite
├── docs/                        # Documentation
├── examples/                    # Usage examples
├── pyproject.toml              # Project configuration
└── README_PYTHON.md           # This file

📚 Documentation

API Documentation - Detailed MCP tools API reference
Migration Guide - Migrating from TypeScript version
Examples - Usage examples and configurations
Test Documentation - Testing guide and coverage
Troubleshooting - Common issues and solutions

🔄 Migration from TypeScript Version

This Python implementation is designed to be fully compatible with the TypeScript version. See our Migration Guide for detailed instructions on switching from the TypeScript implementation.

Key Differences

Feature	TypeScript	Python
Framework	Native TS	FastMCP
Performance	Good	Enhanced
Async Support	Promise-based	Native async/await
Type Safety	TypeScript	Pydantic
Testing	Jest	pytest
Packaging	npm	pip/uv

API Compatibility

All MCP tools maintain the same interface:

✅ execute-command - Full compatibility
✅ upload - Full compatibility
✅ download - Full compatibility
✅ list-servers - Full compatibility

🚀 Deployment

Docker Deployment (Coming Soon)

# Build Docker image
docker build -t fastmcp-ssh-server .

# Run container
docker run -d --name ssh-mcp-server \
    -e SSH_HOST=example.com \
    -e SSH_USER=myuser \
    -e SSH_PASS=mypass \
    fastmcp-ssh-server

Systemd Service

# /etc/systemd/system/fastmcp-ssh-server.service
[Unit]
Description=FastMCP SSH Server
After=network.target

[Service]
Type=simple
User=mcp
WorkingDirectory=/opt/fastmcp-ssh-server
ExecStart=/opt/fastmcp-ssh-server/.venv/bin/fastmcp-ssh-server \
    --host prod.example.com \
    --username deploy \
    --private-key /opt/fastmcp-ssh-server/keys/deploy.key
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Production Considerations

Security: Use private key authentication in production
Logging: Configure structured logging with log rotation
Monitoring: Set up health checks and monitoring
Backup: Regular backup of configuration and keys
Updates: Automated update strategy

🛠️ Troubleshooting

Common Issues

Connection Issues

# Test SSH connection manually
ssh user@host -p port

# Check SSH key permissions
chmod 600 ~/.ssh/id_rsa

# Verbose SSH debugging
ssh -v user@host

Permission Issues

# Check file permissions
ls -la /path/to/private/key

# Fix key permissions
chmod 600 /path/to/private/key
chmod 700 ~/.ssh

Command Execution Issues

# Test command validation
fastmcp-ssh-server --host server.com --username user --password pass \
    --whitelist "ls.*" --blacklist "rm.*"

For more detailed troubleshooting, see docs/troubleshooting.md.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

Code Standards

Python 3.12+ compatibility
Type hints for all functions
Comprehensive tests with 90%+ coverage
Documentation for all public APIs
Security first approach

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🙏 Acknowledgments

FastMCP - The excellent MCP framework
AsyncSSH - Robust SSH implementation
Pydantic - Data validation and settings
Typer - Modern CLI framework

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

FastMCP SSH Server - Empowering AI models with secure, efficient SSH connectivity 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github/workflows		.github/workflows
docs		docs
examples		examples
src/ssh_mcp		src/ssh_mcp
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
uv.lock		uv.lock

Uh oh!

License

Uh oh!

enwaiax/ssh-mcp

Folders and files

Latest commit

History

Repository files navigation

FastMCP SSH Server - Python Implementation

✨ Features

🔌 Core Capabilities

🛡️ Security Features

🚀 Performance & Reliability

📦 Installation

Requirements

Using uv (Recommended)

Using pip

From PyPI (Future)

🚀 Quick Start

1. Basic Usage

2. Security Configuration

3. Configuration File (Coming Soon)

📖 Usage Guide

Command Line Interface

Single Connection Mode

Multiple Connection Mode

Global Security Options

MCP Tools

1. execute-command

2. upload

3. download

4. list-servers

🔧 Configuration

Security Configuration

Command Whitelist

Command Blacklist

Example Security Configurations

Authentication Methods

Password Authentication

Private Key Authentication

Mixed Authentication for Multiple Servers

🧪 Development

Setting up Development Environment

Running Tests

Code Quality

Project Structure

📚 Documentation

🔄 Migration from TypeScript Version

Key Differences

API Compatibility

🚀 Deployment

Docker Deployment (Coming Soon)

Systemd Service

Production Considerations

🛠️ Troubleshooting

Common Issues

Connection Issues

Permission Issues

Command Execution Issues

🤝 Contributing

Development Workflow

Code Standards

📄 License

🙏 Acknowledgments

📞 Support

{{END_MODIFICATIONS}}

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Languages

1. `execute-command`

2. `upload`

3. `download`

4. `list-servers`