Ubuntu VM Control MCP Server

A Model Context Protocol (MCP) server that allows an AI assistant to interact with an Ubuntu VM using SSH.

Purpose

This MCP server provides a secure interface for an AI assistant to perform basic GUI operations on a remote Ubuntu machine. It can execute commands, simulate keyboard and mouse inputs, and capture the screen.

This requires that the target Ubuntu VM has a graphical desktop environment running and the necessary tools (xdotool, scrot) installed.

Features

• execute_command: Executes any shell command on the remote VM.

• type_text: Simulates typing text.

• click: Simulates a mouse click at specified coordinates.

• get_active_window_title: Retrieves the title of the currently active window.

• take_screenshot: Captures the screen and returns the image as a base64-encoded string.

Prerequisites

• Docker Desktop with MCP Toolkit enabled.

• An Ubuntu VM with a desktop environment (e.g., GNOME, XFCE) and an SSH server installed.

• The following tools installed on the Ubuntu VM: xdotool and scrot (sudo apt-get install xdotool scrot).

• SSH key-based authentication configured for accessing the VM.

Installation

See the install_instructions.txt file for step-by-step instructions.

Usage Examples

In Claude Desktop, you can ask:

• "Open a terminal on my Ubuntu VM."

  • (This would use execute_command with a command like gnome-terminal)

• "Type 'hello world' in the active window on my VM."

• "Click on the screen at position 100, 150 on my Ubuntu machine."

• "What is the name of the current window on my VM?"

• "Show me what's on the screen of my Ubuntu VM."

Security Considerations

• SSH Key: The SSH private key is handled as a Docker secret and is stored securely by Docker. It is mounted into the container at runtime and deleted from the container's filesystem upon exit.

• Command Execution: The execute_command tool is very powerful. Be aware of the commands you are asking the assistant to run.

• Network: Ensure that the Docker container can reach the Ubuntu VM over the network.

• Non-Root User: The Docker container runs as a non-root user for better security.