@tb.p/terminai/README.md

MCP (Model Context Protocol) server for secure SSH remote command execution. Enables AI assistants like Claude, Cursor, and VS Code to execute commands on remote servers via SSH with command validation, history tracking, and web-based configuration UI.

# Terminai - MCP Server for SSH Remote Command Execution

**Terminai** is an MCP (Model Context Protocol) server that enables AI assistants like Claude, Cursor, and VS Code to securely execute commands on remote servers via SSH. Features command validation, execution history, web-based configuration UI, and granular permission management.

## Features

- 🔐 **Secure SSH execution** - Execute commands on remote servers via SSH key authentication
- 🛡️ **Command validation** - Allow/deny rules with wildcard support for safe automation
- 📊 **Execution history** - Track all commands with output, timestamps, and status
- 🎨 **Web UI** - Visual interface for managing connections, SSH keys, and permissions
- 🤖 **AI-ready** - Optimized descriptions help AI assistants select the right server
- ⚙️ **Flexible configuration** - Global and per-connection rules, custom config paths

## Installation

Installation steps depend on which AI tool you're using. Follow the instructions for your tool below.

### Claude Desktop

#### Step 1: Initialize Configuration

```bash
npx -y @tb.p/terminai@latest init
```

This creates a default config at `~/.config/terminai/config.json`.

#### Step 2: Add SSH Connections

Open the web UI to manage connections:

```bash
npx -y @tb.p/terminai@latest config --ui
```

This starts a local web server (port 8374) and opens your browser. Add connections, generate SSH keys, and configure permissions.

**Tip:** Once Terminai is configured with your AI tool, you can also ask your AI agent to open the config UI for you!

#### Step 3: Configure Claude Desktop

Edit your Claude Desktop configuration file:

**Config file locations:**
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

**Using npx (recommended):**
```json
{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@tb.p/terminai@latest"]
    }
  }
}
```

**With custom config path:**
```json
{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@tb.p/terminai@latest", "--config", "/path/to/config.json"]
    }
  }
}
```

**Alternative (global install):**
If you prefer global installation:
```bash
npm install -g @tb.p/terminai
```

Then use:
```json
{
  "mcpServers": {
    "ssh": {
      "command": "terminai"
    }
  }
}
```

**Important:** Restart Claude Desktop after editing the configuration file.

### Cursor

#### Step 1: Initialize Configuration

```bash
npx -y @tb.p/terminai@latest init
```

#### Step 2: Add SSH Connections

```bash
npx -y @tb.p/terminai@latest config --ui
```

**Tip:** Once Terminai is configured with your AI tool, you can also ask your AI agent to open the config UI for you!

#### Step 3: Configure Cursor

Edit your Cursor MCP configuration file (typically `~/.cursor/mcp.json` or in Cursor settings):

```json
{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@tb.p/terminai@latest"]
    }
  }
}
```

**With custom config path:**
```json
{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@tb.p/terminai@latest", "--config", "/path/to/config.json"]
    }
  }
}
```

Restart Cursor after editing.

### VS Code (with MCP Extension)

#### Step 1: Install MCP Extension

Install a VS Code extension that supports MCP servers (check VS Code marketplace for MCP extensions).

#### Step 2: Initialize Configuration

```bash
npx -y @tb.p/terminai@latest init
```

#### Step 3: Add SSH Connections

```bash
npx -y @tb.p/terminai@latest config --ui
```

#### Step 4: Configure VS Code

Add Terminai to your VS Code MCP settings (location depends on the extension):

```json
{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@tb.p/terminai@latest"]
    }
  }
}
```

**With custom config path:**
```json
{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@tb.p/terminai@latest", "--config", "/path/to/config.json"]
    }
  }
}
```

Restart VS Code after editing.

## Use Cases & Examples

### Use Case 1: Proxmox VM Management

**Scenario:** Manage Proxmox VMs and containers via AI assistant.

**Configuration:**
```json
{
  "connections": {
    "proxmox": {
      "name": "proxmox",
      "description": "Proxmox VE hypervisor for managing VMs and LXC containers. Commands: qm (VMs), pct (containers), pvesh (API).",
      "host": "192.168.1.100",
      "username": "root",
      "identityFile": "~/.ssh/id_proxmox",
      "allowedCommands": ["qm *", "pct *", "pvesh *"]
    }
  }
}
```

**AI Interaction:**
- User: "Create a new LXC container with 2GB RAM for a wiki server"
- AI: Calls `ssh_list_connections` → finds "proxmox" → executes `pct create ...`

### Use Case 2: Production Web Server Monitoring

**Scenario:** Monitor production servers with read-only access.

**Configuration:**
```json
{
  "connections": {
    "prod-web": {
      "name": "prod-web",
      "description": "Production web server running nginx. Use for checking service status and logs only.",
      "host": "web.example.com",
      "username": "monitor",
      "identityFile": "~/.ssh/id_prod",
      "allowedCommands": ["systemctl status *", "journalctl *", "df -h", "free -h"],
      "disallowedCommands": ["systemctl restart *", "systemctl stop *", "reboot", "shutdown"]
    }
  }
}
```

**AI Interaction:**
- User: "Check if nginx is running on production"
- AI: Executes `systemctl status nginx` on "prod-web"

### Use Case 3: Multi-Environment Management

**Scenario:** Manage dev, staging, and prod environments with different permissions.

**Configuration:**
```json
{
  "global": {
    "allowedCommands": ["ls", "cat", "df", "systemctl status *"],
    "disallowedCommands": ["rm -rf /", "mkfs*"]
  },
  "connections": {
    "dev": {
      "name": "dev",
      "description": "Development server - full access for testing",
      "host": "dev.example.com",
      "username": "deploy",
      "identityFile": "~/.ssh/id_dev",
      "allowedCommands": ["*"]
    },
    "staging": {
      "name": "staging",
      "description": "Staging server - deploy and test before production",
      "host": "staging.example.com",
      "username": "deploy",
      "identityFile": "~/.ssh/id_staging",
      "allowedCommands": ["git *", "npm *", "systemctl restart *"],
      "disallowedCommands": ["rm -rf *"]
    },
    "prod": {
      "name": "prod",
      "description": "Production server - read-only monitoring only",
      "host": "prod.example.com",
      "username": "monitor",
      "identityFile": "~/.ssh/id_prod",
      "allowedCommands": ["systemctl status *", "journalctl *"],
      "disallowedCommands": ["*"]
    }
  }
}
```

### Use Case 4: TrueNAS Storage Management

**Scenario:** Manage ZFS pools and datasets on TrueNAS.

**Configuration:**
```json
{
  "connections": {
    "truenas": {
      "name": "truenas",
      "description": "TrueNAS Scale storage server. Manages ZFS pools, datasets, and SMB/NFS shares. CLI: midclt, zfs, zpool.",
      "host": "truenas.local",
      "username": "root",
      "identityFile": "~/.ssh/id_truenas",
      "allowedCommands": ["midclt *", "zfs *", "zpool *"]
    }
  }
}
```

## CLI Reference

### Start MCP Server

```bash
# Use default config (~/.config/terminai/config.json)
npx -y @tb.p/terminai@latest

# Use custom config file
npx -y @tb.p/terminai@latest --config /path/to/config.json

# Use config from environment variable
SSH_MCP_CONFIG=/path/to/config.json npx -y @tb.p/terminai@latest
```

### Configuration Management

```bash
# Initialize default config
npx -y @tb.p/terminai@latest init

# Initialize config at custom path
npx -y @tb.p/terminai@latest init --config /custom/path/config.json

# Show config file location
npx -y @tb.p/terminai@latest config

# Open web UI (default port 8374)
npx -y @tb.p/terminai@latest config --ui

# Open web UI on custom port
npx -y @tb.p/terminai@latest config --ui --port 3000

# Open web UI with custom config
npx -y @tb.p/terminai@latest config --ui --config /path/to/config.json
```

**Note:** If you installed globally, you can use `terminai` instead of `npx -y @tb.p/terminai@latest`.

### Config File Resolution Order

1. `--config` CLI flag
2. `SSH_MCP_CONFIG` environment variable
3. `~/.config/terminai/config.json` (default)

## Configuration

### Global Settings

```json
{
  "global": {
    "allowedCommands": ["ls", "cat", "df", "systemctl status *"],
    "disallowedCommands": ["rm -rf /", "mkfs*", "shutdown"],
    "defaultTimeout": 30000,
    "historyLimit": 500,
    "historyRetentionDays": 30,
    "logOutput": true,
    "outputMaxLength": 10000,
    "redactPatterns": [
      "(?i)password[=:]\\S+",
      "(?i)token[=:]\\S+",
      "(?i)secret[=:]\\S+"
    ]
  }
}
```

**Options:**
- `allowedCommands` - Globally allowed command patterns (wildcards supported)
- `disallowedCommands` - Globally denied command patterns
- `defaultTimeout` - Command timeout in milliseconds (default: 30000)
- `historyLimit` - Max history entries per connection (default: 500)
- `historyRetentionDays` - Days to retain history (default: 30)
- `logOutput` - Log command output to history (default: true)
- `outputMaxLength` - Max output length to store (default: 10000)
- `redactPatterns` - Regex patterns to redact sensitive data

### Connection Settings

```json
{
  "connections": {
    "my-server": {
      "name": "my-server",
      "description": "Server description for AI context",
      "host": "192.168.1.10",
      "port": 22,
      "username": "user",
      "identityFile": "~/.ssh/id_rsa",
      "allowedCommands": ["systemctl restart nginx"],
      "disallowedCommands": ["reboot", "shutdown"]
    }
  }
}
```

**Required fields:**
- `name` - Unique connection identifier
- `host` - Hostname or IP address
- `username` - SSH username
- `identityFile` - Path to private SSH key

**Optional fields:**
- `description` - Human-readable description (important for AI selection)
- `port` - SSH port (default: 22)
- `allowedCommands` - Connection-specific allowed commands
- `disallowedCommands` - Connection-specific denied commands

### Writing Good Descriptions

The `description` field helps AI assistants select the right server. Include:

1. **What is this server?** - "Proxmox VE hypervisor", "Production database"
2. **What is it used for?** - "Managing VMs", "PostgreSQL primary"
3. **Available commands/tools** - "Commands: qm, pct, pvesh"
4. **Restrictions** - "Read-only access", "No restarts during business hours"

**Examples:**
```
"Proxmox VE hypervisor for managing VMs and LXC containers. Commands: qm (VMs), pct (containers)."

"Production web server running nginx. Use for checking service status only."

"Development sandbox - full access for testing."
```

## Command Validation

Commands are validated in this order (first match wins):

1. Connection-specific `disallowedCommands` → **DENY**
2. Global `disallowedCommands` → **DENY**
3. Connection-specific `allowedCommands` → **ALLOW**
4. Global `allowedCommands` → **ALLOW**
5. Default → **DENY**

**Wildcard support:**
- `*` matches anything
- `systemctl status *` allows `systemctl status nginx`, `systemctl status mysql`, etc.

**Example:**
```json
{
  "global": {
    "allowedCommands": ["ls", "cat"],
    "disallowedCommands": ["rm -rf /"]
  },
  "connections": {
    "dev": {
      "allowedCommands": ["*"]
    }
  }
}
```

- Any server: `ls` → ALLOWED (global)
- Any server: `rm -rf /` → DENIED (global)
- Dev server: `reboot` → ALLOWED (connection wildcard)

## Web UI

Start the web UI manually:

```bash
npx -y @tb.p/terminai@latest config --ui
```

**Or ask your AI agent:** Once Terminai is configured with your AI tool, you can simply ask your AI agent to "open the Terminai config UI" and it will launch the web interface for you.

**Features:**
- Add/edit/remove SSH connections
- Generate SSH key pairs (ed25519 or RSA)
- Browse files to select identity files
- View command execution history
- Configure global allow/deny rules
- Test connections
- View public keys

**Security:** The web UI binds to localhost only and is never exposed to the network.

## Available MCP Tools

When integrated with an AI tool, these tools become available:

| Tool | Description |
|------|-------------|
| `terminai_list_connections` | List all configured SSH connections with descriptions |
| `terminai_exec` | Execute a command on a remote server |
| `terminai_get_history` | Get command execution history for a connection |
| `terminai_get_config` | Get current configuration |
| `terminai_add_connection` | Add a new SSH connection |
| `terminai_update_connection` | Update an existing connection |
| `terminai_remove_connection` | Remove a connection |
| `terminai_open_config_ui` | Open the web-based configuration UI in your browser |

## History

Command execution history is stored at `~/.config/terminai/history.json`.

**History entries include:**
- Command executed
- Timestamp
- Exit code
- Duration
- Status (success, error, denied, timeout)
- stdout/stderr output (if logging enabled)

History is automatically pruned based on `historyRetentionDays` and `historyLimit` settings.

## Security

1. **Web UI** - Binds to localhost only, never exposed to network
2. **SSH keys** - Protect private keys with `chmod 600`
3. **Command validation** - Advisory only, not a security boundary
4. **Output redaction** - Best-effort pattern matching
5. **History** - May contain sensitive data, clear periodically
6. **Authentication** - SSH key only, no password authentication

## Troubleshooting

### AI tool doesn't see the tools

1. Verify config file exists and is valid JSON
2. Restart your AI tool completely
3. Test manually: `npx -y @tb.p/terminai@latest` (should start and wait for input)
4. If using global install, check `terminai` is in PATH: `which terminai` (Unix) or `where terminai` (Windows)

### SSH connection fails

1. Test manually: `ssh -i ~/.ssh/keyfile user@host`
2. Check key permissions: `chmod 600 ~/.ssh/keyfile`
3. Verify public key is in `~/.ssh/authorized_keys` on remote server
4. Use "Test Connection" in web UI for detailed errors

### Commands are denied

1. Check command against allow/deny rules (connection-specific first, then global)
2. Remember wildcards: `systemctl *` allows all systemctl commands
3. Default is deny - commands must be explicitly allowed

## How It Works

MCP servers are launched automatically by AI tools (not manual background services):

```
┌──────────────┐       stdio        ┌──────────┐
│ AI Tool      │ ◄─── JSON-RPC ────► │ Terminai │
│ (MCP Client) │                    │ (Server) │
└──────────────┘                    └─────┬────┘
                                          │ SSH
                                          ▼
                                    ┌──────────┐
                                    │  Remote  │
                                    │  Server  │
                                    └──────────┘
```

1. AI tool starts and connects to all configured MCP servers
2. Each server reports available tools
3. When you send a prompt, the AI decides which tools to use
4. Terminai executes commands via SSH and returns results

## License

MIT License - see LICENSE file for details.