VNC MCP

Let your MCP-compatible AI see and control a VNC desktop.

Screenshot-based desktop control, packaged as a Windows executable.

Features · Quick start · MCP setup · CLI · License

At a glance

flowchart LR
    AI["MCP host / AI"] <-->|"MCP tools · stdio"| MCP["VNC MCP"]
    MCP <-->|"VNC · RFB"| Desktop["Authorized VNC desktop"]
    MCP -->|"PNG screenshot"| AI

Related MCP server: vnc-mcp

Features

• Inspect the remote screen with PNG screenshots at native resolution.

• Click, move, drag, and scroll the mouse.

• Press, hold, and release keys; type text.

• Send clipboard text and read the latest text announced by the VNC server.

• Keep one connection open for MCP actions, or run one-off CLI commands.

• Connect with or without a VNC password.

VNC input directly controls the remote computer. Connect only to systems you are authorized to use.

Quick start

1. Get the executable

Download and extract vnc-mcp-win-x64.zip, or build it yourself on Windows with Python 3.14:

py -3.14 --version
.\build.ps1

The build creates dist/vnc-mcp.exe and dist/vnc-mcp-win-x64.zip. The ZIP contains both the single-file executable and an onedir build in vnc-mcp/, with the README, license, and attribution notice.

2. Add the MCP server

Add this entry to your MCP host configuration. Replace the executable path with where you extracted it:

{
  "mcpServers": {
    "vnc": {
      "command": "C:\\path\\to\\vnc-mcp.exe",
      "args": ["mcp"],
      "env": {
        "VNC_HOST": "127.0.0.1",
        "VNC_PORT": "5900",
        "VNC_PASSWORD": ""
      }
    }
  }
}

Restart or reload the MCP host. Connect with vnc_connect, then call vnc_screenshot to view the desktop. Use screenshot pixel coordinates for input; take another screenshot to confirm the result.

3. Protect credentials

The password is optional. Prefer your MCP host's protected environment or secret settings for VNC_PASSWORD; avoid saving real credentials in shared config files.

MCP setup

The MCP server communicates over stdio and does not open a listening port. Set these optional environment variables in the MCP host:

Available tools

Suggested interaction: connect → screenshot → act using native pixel coordinates → screenshot again to verify.

CLI

Each CLI command connects, performs one action, prints a JSON result, then disconnects. In an interactive terminal, the CLI prompts for a password without displaying it. For scripts, set VNC_PASSWORD or use --password-env NAME.

.\vnc-mcp.exe --help
.\vnc-mcp.exe screenshot --host 127.0.0.1 --port 5900 --output screen.png
.\vnc-mcp.exe click --host 127.0.0.1 --port 5900 430 280
.\vnc-mcp.exe keypress --host 127.0.0.1 --port 5900 ctrl-alt-delete
.\vnc-mcp.exe type --host 127.0.0.1 --port 5900 "hello world"
.\vnc-mcp.exe drag --host 127.0.0.1 --port 5900 40 80 300 240
.\vnc-mcp.exe scroll --host 127.0.0.1 --port 5900 400 400 down --amount 3
.\vnc-mcp.exe clipboard-set --host 127.0.0.1 --port 5900 "hello world"
.\vnc-mcp.exe clipboard-get --host 127.0.0.1 --port 5900

Run commands from the folder containing vnc-mcp.exe, or use its full path. For command-specific options, run vnc-mcp.exe <command> --help. CLI commands require --host; --port defaults to 5900. Use MCP for a persistent session across multiple actions.

Run from source

Python 3.10 or later can run the project without the packaged executable:

py -m pip install -r requirements.txt
py main.py --help
py main.py mcp

Direct runtime dependencies: vncdotool==1.4.2 and mcp==1.30.0. build.ps1 uses PyInstaller to bundle the app and its runtime dependencies.

License

The original project code is available under the Apache License, Version 2.0. You may use, modify, and redistribute it, including commercially, subject to that license. Keep the accompanying NOTICE attribution when redistributing this project or derivative works: “Shinko is one of the initial developers of VNC MCP.”

Third-party dependencies included in the executable remain under their own licenses.