Metadata-Version: 2.4
Name: remote-terminal-mcp
Version: 1.1.0
Summary: Full SSH terminal for Linux servers with AI/user control and dual-stream visibility
Author-email: Tim <tim00r@github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/TiM00R/remote-terminal
Project-URL: Repository, https://github.com/TiM00R/remote-terminal
Project-URL: Documentation, https://github.com/TiM00R/remote-terminal/tree/main/docs
Project-URL: Bug Tracker, https://github.com/TiM00R/remote-terminal/issues
Keywords: mcp,model-context-protocol,ssh,remote-terminal,linux,server-management,automation,devops,claude,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nicegui>=1.4.0
Requires-Dist: paramiko>=3.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: python-json-logger>=2.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: uvicorn>=0.23.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

# 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**
```powershell
# Choose a location for your installation (example: C:\RemoteTerminal)
mkdir C:\RemoteTerminal
cd C:\RemoteTerminal
```

**Step 2: Create Isolated Environment**
```powershell
# 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**
```powershell
# Create hosts.yaml in this directory
notepad hosts.yaml
```

Example `hosts.yaml`:
```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`:

```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**
```powershell
# 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**
```powershell
git clone https://github.com/TiM00R/remote-terminal.git
cd remote-terminal
```

**Step 2: Create Virtual Environment**
```powershell
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

**Step 3: Configure Servers**
```powershell
# Edit hosts.yaml with your server details
notepad hosts.yaml
```

Example `hosts.yaml`:
```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**
```json
{
    "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)**
```powershell
.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](https://github.com/TiM00R/remote-terminal/blob/main/docs/INSTALLATION.md)**
- **[User Guide](https://github.com/TiM00R/remote-terminal/blob/main/docs/USER_GUIDE.md)**
- **[Feature Reference](https://github.com/TiM00R/remote-terminal/blob/main/docs/FEATURE_REFERENCE.md)**
- **[Troubleshooting](https://github.com/TiM00R/remote-terminal/blob/main/docs/TROUBLESHOOTING.md)**

---

## 📊 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:**

```powershell
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)
