mcp-vnc

mcp-vnc is an MCP server that exposes a set of remote desktop control actions over the Model Context Protocol. It lets AI agents issue mouse, keyboard, and text input commands and capture screen visuals from any host running a VNC server. The available tools include vnc_click for clicking at coordinates, vnc_move_mouse to reposition the cursor, vnc_key_press to send keyboard input or combinations, vnc_type_text and vnc_type_multiline for text entry, and vnc_screenshot to capture the current screen image. This enables automated interactions with remote desktops through MCP, enabling agents to operate Windows, macOS, Linux, or other VNC-enabled environments as if they were local interfaces. The server is packaged for Node.js and can be installed globally or run from source after building.

Prerequisites:

• Node.js >= 22.0.0
• npm (comes with Node.js) or pnpm
• Access to a VNC-enabled host if you plan to connect to a remote machine

Install from npm (global):

npm install -g @hrrrsn/mcp-vnc

Install from source:

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

Run the MCP server (example):

# From npm install path
mcp-vnc

Or if running from source after build:

node dist/index.js

Configure the MCP channel for your client (example using Claude Desktop):

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

Tips:

• Ensure the VNC server on the target machine is configured to accept connections from the MCP host. Set a strong VNC password and consider limiting network access to trusted hosts.
• If using the built-from-source path, set the cwd in your MCP config to the repository root where dist/index.js will be produced after build.
• The vnc_screenshot tool supports a delay parameter to allow the screen to settle before capture. Use appropriate delay values for slower machines.
• Environment variables in the MCP config are placeholders; replace with real host, port, and password as needed. The MCP server communicates via stdio; ensure your client is configured to pass and receive messages through the MCP protocol.
• If you encounter issues connecting to VNC, verify that the VNC server allows connections from the MCP host and that any firewalls permit traffic on the VNC port.