VNC Remote Control for macOS MCP server

This MCP server enables AI systems to remotely control macOS environments through a Docker-based implementation of the Model Context Protocol. It allows AI agents to interact with macOS applications, navigate the interface, and perform complex operations without requiring additional software on the target Mac.

Installation

Prerequisites

• A macOS machine with Screen Sharing enabled (can be skipped if using macstadium.com)
• Docker Desktop installed on your local machine
• Claude Desktop or another MCP-compatible client

Setting Up the MCP Server

1. Enable Screen Sharing on your target Mac This step can be skipped if you're using a Mac from macstadium.com.

   Follow Apple's guide to enable Screen Sharing.

2. Configure Claude Desktop

   Add the MCP server to your Claude Desktop 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"
         ]
       }
     }
   }
   

   Replace the values for MACOS_USERNAME, MACOS_PASSWORD, and MACOS_HOST with your actual credentials and host information.

WebRTC Support via LiveKit

The server includes WebRTC support for improved performance:

1. Set up a LiveKit server or use LiveKit Cloud
2. Configure the appropriate LiveKit environment variables in your configuration

Usage

The MCP server provides various tools for remote macOS control through a standardized API.

Available Tools

Screen Capture

Get a screenshot of the remote desktop:

remote_macos_get_screen

Keyboard Input

Send keyboard input to the remote macOS:

remote_macos_send_keys

Mouse Controls

Move the mouse cursor to specific coordinates:

remote_macos_mouse_move

Perform a mouse click at specific coordinates:

remote_macos_mouse_click

Perform a double-click:

remote_macos_mouse_double_click

Scroll at specific coordinates:

remote_macos_mouse_scroll

Perform drag and drop operations:

remote_macos_mouse_drag_n_drop

Application Management

Open or activate an application:

remote_macos_open_application

Use Cases

This MCP server enables various AI automation scenarios:

• Research and post on social media platforms
• Create videos using native macOS applications
• Automated candidate information collection for recruiting
• Engagement automation for LinkedIn and Twitter
• Email and communication management

Security Considerations

The MCP server only supports Apple Authentication (protocol 30), which uses the Diffie-Hellman key agreement protocol with a 512-bit prime. This protocol is used by macOS 11 to macOS 12 when communicating with OS X 10.11 or earlier clients.

Always ensure you have proper authorization to access and control the remote macOS system, and use secure connections when possible.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.