MCP Ubuntu Server

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

Installation

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

Or use directly with npx:

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)

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

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

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

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

# 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