mcp-vnc

You can remotely control machines running a VNC server by using this MCP server. It exposes a compact set of remote-desktop actions you can trigger from an MCP client, enabling precise mouse, keyboard, text input, and screen capture capabilities across Windows, macOS, Linux, or any environment with a VNC server.

How to use

Connect to the MCP server from your MCP client using the remote MCP endpoint configured for your environment. Once connected, you can perform the following actions to control a VNC session on the target machine:

Tools expose these capabilities:

• Mouse: move the cursor, click at specific coordinates, and perform single or double clicks with configurable buttons.

• Keyboard: send single keys or key combinations, including common modifiers like Ctrl, Alt, and Shift.

• Text input: type single lines or multiple lines, with optional Enter key press after typing.

• Screen capture: take a screenshot with an optional initial delay.

How to install

Prerequisites you need before installing:

Node.js and npm must be available on your system. You can install Node.js from the official site and then use npm to install dependencies.

Choose one of the two installation paths below depending on whether you install from npm or build from source.

npm install -g @hrrrsn/mcp-vnc

git clone https://github.com/hrrrsn/mcp-vnc
cd mcp-vnc
npm install
npm run build

After installing, you configure the MCP client to load the server as an MCP endpoint using one of the provided configurations described in the Configuration section.

Configuration

Configure your MCP client to connect to the VNC MCP controller in one of the following ways. The environment variables define the VNC target that the MCP server will control.

{
  "mcpServers": {
    "vnc-controller": {
      "type": "stdio",
      "command": "mcp-vnc",
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_PASSWORD": "your-vnc-password"
      }
    }
  }
}

{
  "mcpServers": {
    "vnc-controller": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/mcp-vnc",
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_PASSWORD": "your-vnc-password"
      }
    }
  }
}

In both configurations, the host, port, and password must match your VNC server settings. Place these files in the MCP client configuration location used by your environment.

Notes

If you have multiple MCP servers or environments, you can define additional vnc-controller entries following the same schema. Ensure that each entry uses a unique name and that required fields are provided for the chosen connection type.

Available tools

vnc_click

Click at specific screen coordinates, with optional button and double-click behavior.

vnc_move_mouse

Move the mouse cursor to given coordinates.

vnc_key_press

Send a single key or a combination of keys including modifiers like Ctrl or Alt.

vnc_type_text

Type a single line of text with an option to press Enter afterward.

vnc_type_multiline

Type multiple lines by sending an array of strings.

vnc_screenshot

Capture the current screen image with an optional delay before capture.