VNC Remote Control for macOS

by baryhuang

55 stars
1k downloads
Not rated
GitHub

About

Provides secure remote control of macOS machines through VNC protocol, enabling screenshot capture and desktop interaction with mouse and keyboard inputs for remote administration or automated testing.

Details

Author
baryhuang
Repository
baryhuang/mcp-remote-macos-use
GitHub stars
55
Downloads
1,029
License
MIT License
Categories
Productivity, Other, Automation, Design, Developer Tools, AI, Infrastructure, Frontend, Security

Jump to

No Extra API Costs: Free screen processing with your existing Claude Pro plan
 Minimal Setup: Just enable Screen Sharing on the target Mac – no additional software needed

  • Universal Compatibility: Works with all macOS versions, current and future

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name VNC Remote Control for macOS
    Command (node, npx, python, etc.) docker
    Arguments
    • Argument 1 run
    • Argument 2 -i
    • Argument 3 -e
    • Argument 4 MACOS_USERNAME=your_macos_username
    • Argument 5 -e
    • Argument 6 MACOS_PASSWORD=your_macos_password
    • Argument 7 -e
    • Argument 8 MACOS_HOST=your_macos_hostname_or_ip
    • Argument 9 --rm
    • Argument 10 buryhuang/mcp-remote-macos-use:latest
    Environment
    • MACOS_HOST your_macos_hostname_or_ip
    • MACOS_PASSWORD your_macos_password
    • MACOS_USERNAME your_macos_username

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

The server provides Remote MacOs functionality through MCP tools.

Zero Setup on Target Machines: No background applications or agents needed on macOS
 Screen Sharing is All You Need: Control any Mac with Screen Sharing enabled

  • Eliminate Backend Complexity: Unlike other solutions that require running Python applications or background services

remote_macos_get_screen

Connect to a remote macOS machine and get a screenshot of the remote desktop. Uses environment variables for connection details.

remote_macos_send_keys

Send keyboard input to a remote macOS machine. Uses environment variables for connection details.

remote_macos_mouse_move

Move the mouse cursor to specified coordinates on a remote macOS machine, with automatic coordinate scaling. Uses environment variables for connection details.

remote_macos_mouse_click

Perform a mouse click at specified coordinates on a remote macOS machine, with automatic coordinate scaling. Uses environment variables for connection details.

remote_macos_mouse_double_click

Perform a mouse double-click at specified coordinates on a remote macOS machine, with automatic coordinate scaling. Uses environment variables for connection details.

remote_macos_mouse_scroll

Perform a mouse scroll at specified coordinates on a remote macOS machine, with automatic coordinate scaling. Uses environment variables for connection details.

remote_macos_open_application

Opens/activates an application and returns its PID for further interactions.

remote_macos_mouse_drag_n_drop

Perform a mouse drag operation from start point and drop to end point on a remote macOS machine, with automatic coordinate scaling.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "vnc remote control for macos": {
            "env": {
                "MACOS_HOST": "your_macos_hostname_or_ip",
                "MACOS_PASSWORD": "your_macos_password",
                "MACOS_USERNAME": "your_macos_username"
            },
            "args": [
                "run",
                "-i",
                "-e",
                "MACOS_USERNAME=your_macos_username",
                "-e",
                "MACOS_PASSWORD=your_macos_password",
                "-e",
                "MACOS_HOST=your_macos_hostname_or_ip",
                "--rm",
                "buryhuang/mcp-remote-macos-use:latest"
            ],
            "command": "docker"
        }
    }
}

Linux

{
    "env": {
        "MACOS_HOST": "your_macos_hostname_or_ip",
        "MACOS_PASSWORD": "your_macos_password",
        "MACOS_USERNAME": "your_macos_username"
    },
    "args": [
        "run",
        "-i",
        "-e",
        "MACOS_USERNAME=your_macos_username",
        "-e",
        "MACOS_PASSWORD=your_macos_password",
        "-e",
        "MACOS_HOST=your_macos_hostname_or_ip",
        "--rm",
        "buryhuang/mcp-remote-macos-use:latest"
    ],
    "command": "docker"
}

Macos

{
    "env": {
        "MACOS_HOST": "your_macos_hostname_or_ip",
        "MACOS_PASSWORD": "your_macos_password",
        "MACOS_USERNAME": "your_macos_username"
    },
    "args": [
        "run",
        "-i",
        "-e",
        "MACOS_USERNAME=your_macos_username",
        "-e",
        "MACOS_PASSWORD=your_macos_password",
        "-e",
        "MACOS_HOST=your_macos_hostname_or_ip",
        "--rm",
        "buryhuang/mcp-remote-macos-use:latest"
    ],
    "command": "docker"
}

Windows

{
    "env": {
        "MACOS_HOST": "your_macos_hostname_or_ip",
        "MACOS_PASSWORD": "your_macos_password",
        "MACOS_USERNAME": "your_macos_username"
    },
    "args": [
        "run",
        "-i",
        "-e",
        "MACOS_USERNAME=your_macos_username",
        "-e",
        "MACOS_PASSWORD=your_macos_password",
        "-e",
        "MACOS_HOST=your_macos_hostname_or_ip",
        "--rm",
        "buryhuang/mcp-remote-macos-use:latest"
    ],
    "command": "docker"
}

MCP Server - Remote MacOs Use

The first open-source MCP server that enables AI to fully control remote macOS systems.

A direct alternative to OpenAI Operator, optimized specifically for autonomous AI agents with complete desktop capabilities, requiring no additional software installation.

Docker Pulls
License: MIT

Showcases
- Research Twitter and Post Twitter(https://www.youtube.com/watch?v=--QHz2jcvcs)
image

- Use CapCut to create short highlight video(https://www.youtube.com/watch?v=RKAqiNoU8ec)
image

- AI Recruiter: Automated candidate information collection, qualifying applications and sending screening sessions using Mail App
- AI Marketing Intern: LinkedIn engagement - automated following, liking, and commenting with relevant users
- AI Marketing Intern: Twitter engagement - automated following, liking, and commenting with relevant users

To-Do List (Prioritized)

1. Performance Optimization - Match speed of Ubuntu desktop alternatives
2. Apple Scripts Generation - Reduce execution time while maintaining flexibility
3. VNC Cursor Visibility - Improve debugging and demo experience

We welcome contributions!

Features

No Extra API Costs: Free screen processing with your existing Claude Pro plan
 Minimal Setup: Just enable Screen Sharing on the target Mac – no additional software needed
Universal Compatibility: Works with all macOS versions, current and future

Why We Built This

Native macOS Experience Without Compromise

The macOS native ecosystem remains unmatched in user experience today and will continue to be the gold standard for years to come. This is where human capabilities truly thrive, and now your AI can operate in this environment with the same fluency.

Open Architecture By Design

 Universal LLM Compatibility: Work with any MCP Client of your choice Model Flexibility: Seamlessly integrate with OpenAI, Anthropic, or any other LLM provider Future-Proof Integration: Designed to evolve with the MCP ecosystem

Effortless Deployment

Zero Setup on Target Machines: No background applications or agents needed on macOS Screen Sharing is All You Need: Control any Mac with Screen Sharing enabled Eliminate Backend Complexity: Unlike other solutions that require running Python applications or background services

Streamlined Bootstrap Process

 Leverage Claude Desktop's Polished UI: No need for developer-style Python interfaces Intuitive User Experience: Interact with your AI-controlled Mac through a familiar, user-friendly interface Instant Productivity: Start working immediately without configuration hassles

Architecture

remote_macos_use_system_architecture

Installation

- Enable Screen Sharing on MacOs If you rent a mac from macstadium.com, you can skip this step - Connect to your remote MacOs - Install Docker Desktop for local Mac - Add this MCP server to Claude Desktop You can configure Claude Desktop to use the Docker image by adding the following to your Claude configuration: 
{
  "mcpServers": {
    "remote-macos-use": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-e",
        "MACOS_USERNAME=your_macos_username",
        "-e",
        "MACOS_PASSWORD=your_macos_password",
        "-e",
        "MACOS_HOST=your_macos_hostname_or_ip",
        "--rm",
        "buryhuang/mcp-remote-macos-use:latest"
      ]
    }
  }
}

WebRTC Support via LiveKit

This server now includes WebRTC support through LiveKit integration, enabling:
- Low-latency real-time screen sharing
- Improved performance and responsiveness
- Better network efficiency compared to traditional VNC
- Automatic quality adaptation based on network conditions

To use WebRTC features, you'll need to:
1. Set up a LiveKit server or use LiveKit Cloud
2. Configure the LiveKit environment variables as shown in the configuration example above

Developer Instruction

Clone the repo

# Clone the repository
git clone https://github.com/yourusername/mcp-remote-macos-use.git
cd mcp-remote-macos-use

Building the Docker Image

# Build the Docker image
docker build -t mcp-remote-macos-use .

Cross-Platform Publishing

To publish the Docker image for multiple platforms, you can use the docker buildx command. Follow these steps:

1. Create a new builder instance (if you haven't already):

   docker buildx create --use

2. Build and push the image for multiple platforms:

   docker buildx build --platform linux/amd64,linux/arm64 -t buryhuang/mcp-remote-macos-use:latest --push .

3. Verify the image is available for the specified platforms:

   docker buildx imagetools inspect buryhuang/mcp-remote-macos-use:latest

Usage

The server provides Remote MacOs functionality through MCP tools.

Tools Specifications

The server provides the following tools for remote macOS control:

remote_macos_get_screen

Connect to a remote macOS machine and get a screenshot of the remote desktop. Uses environment variables for connection details.

remote_macos_send_keys

Send keyboard input to a remote macOS machine. Uses environment variables for connection details.

remote_macos_mouse_move

Move the mouse cursor to specified coordinates on a remote macOS machine, with automatic coordinate scaling. Uses environment variables for connection details.

remote_macos_mouse_click

Perform a mouse click at specified coordinates on a remote macOS machine, with automatic coordinate scaling. Uses environment variables for connection details.

remote_macos_mouse_double_click

Perform a mouse double-click at specified coordinates on a remote macOS machine, with automatic coordinate scaling. Uses environment variables for connection details.

remote_macos_mouse_scroll

Perform a mouse scroll at specified coordinates on a remote macOS machine, with automatic coordinate scaling. Uses environment variables for connection details.

remote_macos_open_application

Opens/activates an application and returns its PID for further interactions.

remote_macos_mouse_drag_n_drop

Perform a mouse drag operation from start point and drop to end point on a remote macOS machine, with automatic coordinate scaling.

All tools use the environment variables configured during setup instead of requiring connection parameters.

Limitations

- Authentication Support:
- Only Apple Authentication (protocol 30) is supported

Security Note

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

{
    "mcpServers": {
        "vnc remote control for macos": {
            "env": {
                "MACOS_HOST": "your_macos_hostname_or_ip",
                "MACOS_PASSWORD": "your_macos_password",
                "MACOS_USERNAME": "your_macos_username"
            },
            "args": [
                "run",
                "-i",
                "-e",
                "MACOS_USERNAME=your_macos_username",
                "-e",
                "MACOS_PASSWORD=your_macos_password",
                "-e",
                "MACOS_HOST=your_macos_hostname_or_ip",
                "--rm",
                "buryhuang/mcp-remote-macos-use:latest"
            ],
            "command": "docker"
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Playwright

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

92.5k
Automation

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Time

A Model Context Protocol server that provides time and timezone conversion capabilities. It enables LLMs to get current time information and perform timezone…

88.2k
Productivity

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other