Skip to main content
Glama

💻 mcp-vnc

Node.js Version License: MIT npm version

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).

Screenshot

🚀 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"
    }
  }
}

Setting

Default

Description

MCP_TRANSPORT

stdio

Set to http to enable HTTP transport

MCP_PORT

3000

HTTP listen port

🛠️ Available Tools

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

🖱️ Mouse Control

Parameter

Required

Type

Description

Default

x

✅

number

X coordinate

-

y

✅

number

Y coordinate

-

button

❌

string

Mouse button (left, right, middle)

left

double

❌

boolean

Double-click instead of single click

false

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

Parameter

Required

Type

Description

x

✅

number

X coordinate

y

✅

number

Y coordinate

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

⌨️ Keyboard Control

Parameter

Required

Type

Description

key

✅

string

Key or key combination to press

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

Parameter

Required

Type

Description

Default

text

✅

string

Text to type

-

enter

❌

boolean

Press Enter after typing

false

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

Parameter

Required

Type

Description

lines

✅

string[]

Array of lines to type

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

📸 Screen Capture

Parameter

Required

Type

Description

Default

delay

❌

number

Delay before screenshot (0-300000ms)

0

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 tools
vnc_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

    A3.5/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      6
      280 npm
      62
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP-compatible LLMs to interact with any desktop accessible over VNC, providing tools for screen reading (OCR), mouse and keyboard control, and automation.
      13
      AGPL 3.0
    • A
      license
      B
      quality
      D
      maintenance
      Empowers 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.
      21
      1
      MIT