mcp-ssh-frr

MCP SSH Docker Server

A Message Control Protocol (MCP) server that provides SSH and Docker command execution capabilities. This server allows you to execute commands on remote systems and Docker containers through a standardized interface.

Features

• SSH command execution on remote systems
• Docker container command execution
• Real-time command output streaming
• Progress reporting for long-running commands
• Structured JSON output support
• Command cancellation support
• Connection and command timeouts
• Comprehensive error handling

Prerequisites

• Python 3.7+
• SSH access to target system
• Docker installed on target system (for Docker commands)

Installation

Using pip

pip install mcp-ssh-frr

From source

1. Clone the repository:

git clone https://github.com/aweher/mcp-ssh-frr.git
cd mcp-ssh-frr

2. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Install the package in development mode:

pip install -e .

4. Configure SSH:

   • Place your SSH private key in ./config/id_rsa

   • Set up environment variables:

     export SSH_HOST="your-remote-host"
     export SSH_USER="your-username" # Defaults to root
     export SSH_PORT="22"  # Optional, defaults to 22
     

   • Don't forget to add your pubkey into authorized_keys file on your-remote-host

Usage

Starting the Server

python mcp_ssh_docker_server.py

Available Tools

1. SSH Command Execution (ssh_exec)

Execute any command on the remote system:

{
    "name": "ssh_exec",
    "args": {
        "command": "ls",
        "args": ["-la", "/etc"],
        "stream": false,  # Set to true for real-time output
        "structured_output": false  # Set to true for JSON output
    }
}

2. Docker Command Execution (ssh_exec_docker)

Execute commands inside Docker containers:

{
    "name": "ssh_exec_docker",
    "args": {
        "container": "my-container",
        "command": "vtysh",
        "args": ["-c", "show ip bgp"],
        "stream": false,
        "structured_output": false
    }
}

List available containers:

{
    "name": "ssh_exec_docker",
    "args": {
        "list_containers": true,
        "structured_output": false
    }
}

Output Formats

1. Text Output (default):

$ command arg1 arg2
(exit code 0)

output line 1
output line 2

2. Structured JSON Output:

{
    "command": "command arg1 arg2",
    "exit_code": 0,
    "stdout": "output line 1\noutput line 2",
    "stderr": "",
    "duration": 0.123,
    "metadata": {
        "container": "my-container"  // For Docker commands
    }
}

3. Progress Updates (when streaming):

[progress] 45% - Bytes read: 1024

Configuration

Timeouts

• SSH Connection Timeout: 10 seconds
• Command Execution Timeout: 30 seconds
• Stream Maximum Time: 300 seconds (5 minutes)

Buffer Size

• Stream Buffer Size: 1024 bytes

Error Handling

The server handles various error scenarios:

• Connection timeouts
• Authentication failures
• Command execution errors
• Docker container errors
• Command cancellation

Security

• Uses SSH key-based authentication
• Command arguments are properly escaped
• No command injection vulnerabilities
• Secure connection handling

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

GPLv3

Author

Ariel S. Weher <ariel[at]weher.net>