tunnel-manager 0.0.2

Create SSH Tunnels to your remote hosts and host as an MCP Server for Agentic AI!

Tunnel Manager

Version: 0.0.2

This project provides a Python-based Tunnel class for secure SSH connections and file transfers, integrated with a FastMCP server (tunnel_mcp.py) to expose these capabilities as tools for AI-driven workflows. The implementation supports both standard SSH (e.g., for local networks) and Teleport's secure access platform, leveraging the paramiko library for SSH operations.

Features

Tunnel Class

• Purpose: Facilitates secure SSH connections and file transfers to remote hosts.
• Key Functionality:
  • Run Remote Commands: Execute shell commands on a remote host and retrieve output.
  • File Upload/Download: Transfer files to/from a remote host using SFTP.
  • Teleport Support: Seamlessly integrates with Teleport's certificate-based authentication and proxying.
  • Configuration Flexibility: Loads SSH settings from ~/.ssh/config by default, with optional overrides for identity files, certificates, and proxy commands.
  • Logging: Optional file-based logging for debugging and auditing.

FastMCP Server

• Purpose: Exposes Tunnel class functionality as a FastMCP server, enabling AI tools to perform remote operations programmatically.
• Tools Provided:
  • run_remote_command: Runs a shell command on a remote host and returns output.
  • upload_file: Uploads a file to a remote host via SFTP.
  • download_file: Downloads a file from a remote host via SFTP.
• Transport Options: Supports stdio (for local scripting) and http (for networked access) transport modes.
• Progress Reporting: Integrates with FastMCP's Context for progress updates during operations.
• Logging: Comprehensive logging to a file (tunnel_mcp.log by default).

Usage:

Tunnel Class

The Tunnel class can be used standalone for SSH operations. Example:

from tunnel_manager import Tunnel

# Initialize with a remote host (assumes ~/.ssh/config or explicit params)
tunnel = Tunnel(
    remote_host="example.com",
    identity_file="/path/to/id_rsa",
    certificate_file="/path/to/cert",  # Optional for Teleport
    proxy_command="tsh proxy ssh %h",  # Optional for Teleport
    log_file="tunnel.log"
)

# Connect and run a command
tunnel.connect()
out, err = tunnel.run_command("ls -la /tmp")
print(f"Output: {out}\nError: {err}")

# Upload a file
tunnel.send_file("/local/file.txt", "/remote/file.txt")

# Download a file
tunnel.receive_file("/remote/file.txt", "/local/downloaded.txt")

# Close the connection
tunnel.close()

FastMCP Server

The FastMCP server exposes the Tunnel functionality as AI-accessible tools. Start the server with:

python tunnel_mcp.py --transport stdio

Or for HTTP transport:

python tunnel_mcp.py --transport http --host 127.0.0.1 --port 8080

Installation Instructions:

Use with AI

Configure mcp.json

{
  "mcpServers": {
    "tunnel_manager": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "tunnel-manager",
        "tunnel-manager-mcp"
      ],
      "env": {
        "TUNNEL_REMOTE_HOST": "user@192.168.1.12", // Optional
        "TUNNEL_REMOTE_PORT": "22",                // Optional
        "TUNNEL_IDENTITY_FILE": "",                // Optional
        "TUNNEL_CERTIFICATE": "",                  // Optional
        "TUNNEL_PROXY_COMMAND": "",                // Optional
        "TUNNEL_LOG_FILE": "~./tunnel_log.txt"     // Optional
      },
      "timeout": 200000
    }
  }
}

Deploy MCP Server as a container

docker pull knucklessg1/tunnel-manager:latest

Modify the compose.yml

services:
  tunnel-manager:
    image: knucklessg1/tunnel-manager:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8021
    ports:
      - 8021:8021

Install Python Package

python -m pip install tunnel-manager

or

uv pip install --upgrade tunnel-manager

Repository Owners: