💻 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-vnc

Install from Source

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

Related MCP server: mcp-vnc

⚙️ Configuration

Claude Desktop

1. Locate and open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. 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 3000

The MCP endpoint is then available at http://localhost:3000/mcp. Client configuration example:

{
  "mcpServers": {
    "vnc-controller": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

🛠️ Available Tools

The MCP server provides the following tools for remote desktop control:

🖱️ Mouse Control

Example: vnc_click(x=100, y=200, button="right", double=true)

Example: vnc_move_mouse(x=500, y=300)

⌨️ Keyboard Control

Supported Keys:

• Single keys: a, Enter, F1, Escape, Up, Down, Tab, Space

• Key combinations: Ctrl+c, Alt+F4, Ctrl+Alt+Delete, Shift+Tab

• Modifiers: Ctrl, Alt, Shift, Super/Win, Meta/Cmd

Examples:

• vnc_key_press(key="Enter")

• vnc_key_press(key="Ctrl+Alt+Delete")

📝 Text Input

Example: vnc_type_text(text="Hello World!", enter=true)

Example: vnc_type_multiline(lines=["Line 1", "Line 2", "Line 3"])

📸 Screen Capture

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.