npm package: @marcelocorrea/mcp-ubuntu-server
Description: MCP server for SSH remote access to Ubuntu VMs, focused on Laravel deployment
Author: Marcelo Correa
Latest version: 1.1.0

# MCP Ubuntu Server

MCP server for SSH remote access to Ubuntu VMs, focused on Laravel deployment (service management, Apache, Git, package installation).

## Installation

```bash
npm install -g @marcelocorrea/mcp-ubuntu-server
```

Or use directly with npx:

```bash
npx @marcelocorrea/mcp-ubuntu-server
```

## Features

- **SSH Connection Management**: Connect to Ubuntu VMs with password or private key authentication
- **Environment Variables**: Pre-configure credentials via environment variables
- **Command Execution**: Run any command on the remote VM (apt, systemctl, git, php artisan, etc.)
- **File Transfer**: Upload and download files via SFTP
- **Directory Listing**: List remote files and directories

## Environment Variables

Configure SSH credentials via environment variables for secure, reusable connections:

| Variable | Required | Description |
|----------|----------|-------------|
| `SSH_HOST` | Yes | IP address or hostname of the VM |
| `SSH_PORT` | No | SSH port (default: 22) |
| `SSH_USERNAME` | Yes | SSH username |
| `SSH_PASSWORD` | No* | Password for authentication |
| `SSH_PRIVATE_KEY` | No* | Private key content (the actual key, not path) |
| `SSH_PRIVATE_KEY_PATH` | No* | Path to private key file (.pem/.key) |

*Must provide either `SSH_PASSWORD`, `SSH_PRIVATE_KEY`, or `SSH_PRIVATE_KEY_PATH`

## Available Tools

### `ssh_connect`

Establish SSH connection to an Ubuntu VM with explicit parameters.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| host | string | Yes | IP address or hostname |
| port | number | No | SSH port (default: 22) |
| username | string | Yes | SSH username |
| password | string | No* | Password authentication |
| privateKey | string | No* | Private key content |
| privateKeyPath | string | No* | Path to private key file |

*Must provide either `password`, `privateKey`, or `privateKeyPath`

### `ssh_connect_env`

Establish SSH connection using environment variables. No parameters needed - uses `SSH_HOST`, `SSH_USERNAME`, and authentication from environment.

### `ssh_exec`

Execute commands on the connected VM.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| command | string | Yes | Command to execute |
| timeout | number | No | Timeout in ms (default: 30000) |

### `ssh_disconnect`

Close the active SSH connection.

### `ssh_upload`

Upload a file to the remote VM via SFTP.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| localPath | string | Yes | Local file path |
| remotePath | string | Yes | Remote destination path |

### `ssh_download`

Download a file from the remote VM via SFTP.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| remotePath | string | Yes | Remote file path |
| localPath | string | Yes | Local destination path |

### `ssh_list_files`

List files and directories on the remote VM.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | No | Remote path (default: ".") |

## Usage with Claude Code

Add to your Claude Code MCP settings (`~/.claude/mcp.json`):

### With environment variables (recommended)

```json
{
  "mcpServers": {
    "ubuntu-server": {
      "command": "npx",
      "args": ["@marcelocorrea/mcp-ubuntu-server"],
      "env": {
        "SSH_HOST": "192.168.1.100",
        "SSH_PORT": "22",
        "SSH_USERNAME": "ubuntu",
        "SSH_PRIVATE_KEY_PATH": "/home/user/.ssh/my-server.pem"
      }
    }
  }
}
```

### With password authentication

```json
{
  "mcpServers": {
    "ubuntu-server": {
      "command": "npx",
      "args": ["@marcelocorrea/mcp-ubuntu-server"],
      "env": {
        "SSH_HOST": "192.168.1.100",
        "SSH_USERNAME": "ubuntu",
        "SSH_PASSWORD": "your-password"
      }
    }
  }
}
```

### Multiple servers

```json
{
  "mcpServers": {
    "production-server": {
      "command": "npx",
      "args": ["@marcelocorrea/mcp-ubuntu-server"],
      "env": {
        "SSH_HOST": "prod.example.com",
        "SSH_USERNAME": "deploy",
        "SSH_PRIVATE_KEY_PATH": "/home/user/.ssh/prod.pem"
      }
    },
    "staging-server": {
      "command": "npx",
      "args": ["@marcelocorrea/mcp-ubuntu-server"],
      "env": {
        "SSH_HOST": "staging.example.com",
        "SSH_USERNAME": "deploy",
        "SSH_PRIVATE_KEY_PATH": "/home/user/.ssh/staging.pem"
      }
    }
  }
}
```

## Usage with Claude Desktop

Add to your Claude Desktop configuration (`~/.config/Claude/claude_desktop_config.json` on Linux or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "ubuntu-server": {
      "command": "npx",
      "args": ["@marcelocorrea/mcp-ubuntu-server"],
      "env": {
        "SSH_HOST": "192.168.1.100",
        "SSH_USERNAME": "ubuntu",
        "SSH_PRIVATE_KEY_PATH": "/path/to/key.pem"
      }
    }
  }
}
```

## Example Usage

### Using environment variables (simpler)

1. Connect using pre-configured credentials:
```
ssh_connect_env
```

2. Run commands:
```
ssh_exec with command="sudo apt update"
```

3. Disconnect:
```
ssh_disconnect
```

### Using explicit parameters

1. Connect to your Ubuntu VM:
```
ssh_connect with host="192.168.1.100", username="ubuntu", privateKeyPath="/path/to/key.pem"
```

2. Update packages:
```
ssh_exec with command="sudo apt update && sudo apt upgrade -y"
```

3. Deploy Laravel application:
```
ssh_exec with command="cd /var/www/myapp && git pull origin main"
ssh_exec with command="cd /var/www/myapp && composer install --no-dev"
ssh_exec with command="cd /var/www/myapp && php artisan migrate --force"
ssh_exec with command="sudo systemctl restart apache2"
```

4. Disconnect when done:
```
ssh_disconnect
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

# Test with environment variables
SSH_HOST=192.168.1.100 SSH_USERNAME=ubuntu SSH_PRIVATE_KEY_PATH=~/.ssh/key.pem \
  npx @modelcontextprotocol/inspector node build/index.js
```

## License

MIT