mcp-vnc
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-vnc Take a screenshot of the remote desktop and describe what you see"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
💻 mcp-vnc
A Model Context Protocol (MCP) server that enables AI agents to remotely control Windows, Linux, macOS or anything else that can run a VNC server (don't worry, it's probably fine).

🚀 Quick Start
Install from NPM
npm install -g @hrrrsn/mcp-vncInstall from Source
git clone https://github.com/hrrrsn/mcp-vnc
cd mcp-vnc
npm install
npm run buildRelated MCP server: mcp-vnc
⚙️ Configuration
Claude Desktop
Locate and open your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Add the following configuration:
Using NPM Install:
{
"mcpServers": {
"vnc-controller": {
"type": "stdio",
"command": "mcp-vnc",
"env": {
"VNC_HOST": "192.168.1.100",
"VNC_PORT": "5900",
"VNC_PASSWORD": "your-vnc-password",
"VNC_TIMEOUT": "30000"
}
}
}
}Built from Source:
{
"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",
"VNC_TIMEOUT": "30000"
}
}
}
}VNC_TIMEOUT (optional) sets how long each tool call waits for the VNC server to
connect and deliver the initial frame, in milliseconds. Defaults to 30000.
VS Code
Please refer to the VS Code documentation
HTTP Transport (Streamable HTTP)
By default the server uses stdio. To expose it over HTTP instead:
# Via environment variables
VNC_HOST=192.168.1.100 VNC_PORT=5900 VNC_PASSWORD=secret \
MCP_TRANSPORT=http MCP_PORT=3000 mcp-vnc
# Or via CLI arguments
mcp-vnc --http --port 3000The MCP endpoint is then available at http://localhost:3000/mcp. Client configuration example:
{
"mcpServers": {
"vnc-controller": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}Setting | Default | Description |
|
| Set to |
|
| HTTP listen port |
🛠️ Available Tools
The MCP server provides the following tools for remote desktop control:
🖱️ Mouse Control
Parameter | Required | Type | Description | Default |
| ✅ | number | X coordinate | - |
| ✅ | number | Y coordinate | - |
| ❌ | string | Mouse button ( |
|
| ❌ | boolean | Double-click instead of single click |
|
Example: vnc_click(x=100, y=200, button="right", double=true)
Parameter | Required | Type | Description |
| ✅ | number | X coordinate |
| ✅ | number | Y coordinate |
Example: vnc_move_mouse(x=500, y=300)
⌨️ Keyboard Control
Parameter | Required | Type | Description |
| ✅ | string | Key or key combination to press |
Supported Keys:
Single keys:
a,Enter,F1,Escape,Up,Down,Tab,SpaceKey combinations:
Ctrl+c,Alt+F4,Ctrl+Alt+Delete,Shift+TabModifiers:
Ctrl,Alt,Shift,Super/Win,Meta/Cmd
Examples:
vnc_key_press(key="Enter")vnc_key_press(key="Ctrl+Alt+Delete")
📝 Text Input
Parameter | Required | Type | Description | Default |
| ✅ | string | Text to type | - |
| ❌ | boolean | Press Enter after typing |
|
Example: vnc_type_text(text="Hello World!", enter=true)
Parameter | Required | Type | Description |
| ✅ | string[] | Array of lines to type |
Example: vnc_type_multiline(lines=["Line 1", "Line 2", "Line 3"])
📸 Screen Capture
Parameter | Required | Type | Description | Default |
| ❌ | number | Delay before screenshot (0-300000ms) |
|
Example: vnc_screenshot(delay=1000) - Wait 1 second before capture
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
Available Tools
6 toolsvnc_clickB
Click at specified coordinates
Inputs: x (required), y (required), button, double.
vnc_key_pressC
Press a key or key combination
Inputs: key (required).
vnc_move_mouseB
Move mouse to specified coordinates
Inputs: x (required), y (required).
vnc_screenshotA
Take a screenshot of the current screen
Inputs: delay.
vnc_type_multilineA
Type multiple lines of text, separated by newlines
Inputs: lines (required).
vnc_type_textC
Type text string
Inputs: text (required), enter.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct input or capture action, so agents can generally tell them apart. vnc_type_text and vnc_type_multiline overlap somewhat, but the multiline description clarifies its intended use.
All tools use the vnc_ prefix with clear lower_snake_case names, making the set predictable. Minor deviations exist, such as vnc_click lacking an object and vnc_screenshot being noun-like, but the pattern remains readable.
Six tools is well-scoped for a VNC control server, covering mouse, keyboard, text, and screen capture without unnecessary bloat. Every tool serves a clear purpose in the remote-control workflow.
The core interaction surface is covered: clicking, moving, key presses, text entry, and screenshots. More advanced input actions like scrolling, right-clicking, or dragging are absent, but common remote-control tasks can still be accomplished.
Maintenance
Related MCP Connectors
Reach your own computers from any AI app: files, commands, screen and mouse, approvals and alerts.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Give your AI hands on every computer you own. Remote control of your Windows, Mac and Linux machines from one ChatGPT, Claude or Cursor chat — even from your phone. Ask it to find out why the office server is crawling, update every PC in the house, sort out your mom's laptop from another city, or ship the site from your work machine while you're on a train. It runs commands, reads files and takes a screenshot when it needs to see the screen. You decide what each computer allows, and you can cut any of them off in a second.
Real desktops for AI agents, on machines you choose: screenshot, type, click, hire more agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI to remotely control macOS systems via VNC with full desktop capabilities including screenshots, mouse control, keyboard input, and application management. Includes a web-based chat interface for natural language control.811MIT
- AlicenseAqualityDmaintenanceAn MCP server that allows AI agents to remotely control Windows, Linux, and macOS systems via VNC. It provides tools for mouse and keyboard interaction, text input, and screen capturing.6280 npm62MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible LLMs to interact with any desktop accessible over VNC, providing tools for screen reading (OCR), mouse and keyboard control, and automation.13AGPL 3.0
- AlicenseBqualityDmaintenanceEmpowers AI agents to see, reason, and control computers via VNC, providing advanced vision features like OCR and image search, human-like input control, and optional SSH remote command execution.211MIT