remote-terminal-mcp 1.1.0

Full SSH terminal for Linux servers with AI/user control and dual-stream visibility

Remote Terminal

AI-Powered Remote Linux Server Management via MCP

Remote Terminal lets Claude (the AI assistant) execute commands on your remote Linux servers through a natural chat interface. Watch full output in your browser in real-time while Claude receives smart-filtered summaries optimized for token efficiency.

---

🚀 Quick Start

Method 1: PyPI Installation (Recommended)

Step 1: Create Installation Directory

# Choose a location for your installation (example: C:\RemoteTerminal)
mkdir C:\RemoteTerminal
cd C:\RemoteTerminal

Step 2: Create Isolated Environment

# Create dedicated virtual environment in this directory
python -m venv remote-terminal-env
remote-terminal-env\Scripts\activate
pip install remote-terminal-mcp

Step 3: Setup Configuration Files

# Create hosts.yaml in this directory
notepad hosts.yaml

Example hosts.yaml:

servers:
  - name: My Server
    host: 192.168.1.100
    user: username
    password: your_password
    port: 22
    description: My development server
    tags:
      - development

default_server: My Server

Step 4: Configure Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
    "mcpServers": {
        "remote-terminal": {
            "command": "C:\\RemoteTerminal\\remote-terminal-env\\Scripts\\remote-terminal-mcp.exe"
        }
    }
}

Important: Replace C:\RemoteTerminal with your actual installation path from Step 1.

Restart Claude Desktop and test:

List my configured servers

Step 5: (Optional) Run Standalone Web Interface

# From your installation directory
cd C:\RemoteTerminal
remote-terminal-env\Scripts\activate
remote-terminal-standalone

Access at:

• Control Panel: http://localhost:8081
• Terminal: http://localhost:8082

---

Method 2: GitHub Installation (Development)

Step 1: Clone Repository

git clone https://github.com/TiM00R/remote-terminal.git
cd remote-terminal

Step 2: Create Virtual Environment

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Step 3: Configure Servers

# Edit hosts.yaml with your server details
notepad hosts.yaml

Example hosts.yaml:

servers:
  - name: production
    host: 192.168.1.100
    user: admin
    password: secure_pass
    port: 22
    description: Production server
    tags:
      - production
    
  - name: development
    host: 192.168.1.101
    user: dev
    password: dev_pass
    tags:
      - development

default_server: production

Step 4: Configure Claude Desktop

{
    "mcpServers": {
        "remote-terminal": {
            "command": "D:\\path\\to\\remote-terminal\\.venv\\Scripts\\python.exe",
            "args": ["D:\\path\\to\\remote-terminal\\src\\mcp_server.py"]
        }
    }
}

Step 5: Run Standalone (Optional)

.venv\Scripts\activate
python standalone\standalone_mcp.py

---

📁 Configuration Files Location

• PyPI Install: Config files in your installation directory (e.g., C:\RemoteTerminal\)
• GitHub Install: Config files in project root (remote-terminal\)

The tool automatically looks for hosts.yaml and config.yaml in:

1. Current working directory (for PyPI users)
2. Project root directory (for GitHub users)

Database is created in data\remote_terminal.db relative to config file location.

---

✨ Key Features

• 🖥️ Remote Command Execution - Run any bash command on Linux servers
• 🌐 Multi-Server Management - Switch between multiple servers easily
• 📁 File Transfer (SFTP) - Upload/download files and directories
• 📜 Batch Script Execution - Run multi-command scripts 10-50x faster
• 📚 Batch Script Library - Save, browse, and reuse scripts
• 💬 Conversation Tracking - Group commands by goal with rollback
• 🎯 Recipe System - Save successful workflows for reuse
• 🌍 Interactive Web Terminal - Full-featured terminal in browser
• 📊 Token Efficiency - 95-98% token reduction on verbose commands

---

💡 Usage Examples

"List my configured servers"
"Connect to My Server"
"Check disk space and memory usage"
"Install nginx and configure it with SSL"
"Upload config.json to /etc/app/"
"Run network diagnostics and summarize"
"List my saved batch scripts"
"Execute script 5"

---

📖 Documentation

• Installation Guide
• User Guide
• Feature Reference
• Troubleshooting

---

📊 Performance

Token Efficiency: 95-98% reduction on verbose commands

Command Type	Full Output	Filtered	Savings
apt install	~15,000	~600	96%
ls -la /var	~8,000	~400	95%
find /	~30,000	~800	97%

Speed: Batch execution is 10x faster than sequential commands

---

🛡️ Security

• Passwords in plain text hosts.yaml (protect with file permissions)
• Web terminal on localhost only (not exposed to network)
• Full command audit trail in database
• SSH key support coming soon

---

📞 Support

• GitHub Issues: https://github.com/TiM00R/remote-terminal/issues
• Documentation: https://github.com/TiM00R/remote-terminal/tree/main/docs

---

📄 License

MIT License - See LICENSE file for details

---

Get started now:

mkdir C:\RemoteTerminal
cd C:\RemoteTerminal
python -m venv remote-terminal-env
remote-terminal-env\Scripts\activate
pip install remote-terminal-mcp

Version: 1.1.0 | Maintainer: Tim (TiM00R)