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

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:

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):

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

With custom config path:

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

Alternative (global install): If you prefer global installation:

npm install -g @tb.p/terminai

Then use:

{
  "mcpServers": {
    "ssh": {
      "command": "terminai"
    }
  }
}

Important: Restart Claude Desktop after editing the configuration file.

Cursor

Step 1: Initialize Configuration

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

Step 2: Add SSH Connections

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):

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

With custom config path:

{
  "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

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

Step 3: Add SSH Connections

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):

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

With custom config path:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

# 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

# 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

{
  "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

{
  "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:

{
  "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:

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.