MCP macOS Server

You can use this MCP server to remotely control macOS systems with an AI-assisted chat interface. It combines a Python MCP backend with a modern web UI to send commands, view results, and automate tasks on a Mac that has Screen Sharing enabled. This setup is designed for practical control, scripting, and interactive use from a web browser or an MCP client.

How to use

You connect to the MCP server from an MCP client or the included web UI. The AI-driven chat analyzes your natural language commands and translates them into macOS actions via the MCP backend and the Screen Sharing channel. Typical tasks include taking screenshots, launching apps, clicking UI elements, typing text, and navigating the desktop. Use concise commands like “Take a screenshot,” “Open Safari,” or “Click on the Dock.” The system handles the translation and execution, returning results or visual feedback when appropriate.

How to install

# Prerequisites
# - Docker Desktop installed
# - Node.js 18+ installed
# - A Mac with Screen Sharing enabled

# 1. Clone and Setup
git clone <repository-url>
cd mcp_macos

# Install root dependencies
npm install

# Install frontend and backend dependencies
npm run install:all

# 2. Configure Environment
cp backend/.env.example backend/.env
# Edit backend/.env with your settings:
# - MACOS_HOST=localhost
# - MACOS_PASSWORD=your_vnc_password
# - OPENAI_API_KEY=your_openai_api_key

# 3. Enable Screen Sharing (macOS)
# Open System Preferences > Sharing
# Enable "Screen Sharing" and set a VNC password when prompted

# 4. Run the Application
# Start both frontend and backend
npm run dev

# Or start individually:
npm run dev:frontend  # Frontend on http://localhost:3000
npm run dev:backend   # Backend on http://localhost:3001

# 5. Open and Chat!
# Open the UI in your browser
# http://localhost:3000
# Wait for connection to establish
# Try commands like: "Take a screenshot", "Open Safari", "Click on the Dock", "Type hello world"

Configuration and security

Environment settings are configured in a backend environment file. You should specify the target macOS host, the VNC password, and your OpenAI API key. Use these variables to tailor the connection and AI behavior to your environment.

Security reminders:

• Only operate on Macs you own or have explicit permission to control.
• VNC passwords are used for screen sharing authentication; ensure they are strong and keep them confidential.
• OpenAI API keys are stored server-side only.
• All actions are logged for debugging and auditing.

Project structure and development commands

The project includes a Next.js frontend, a Node.js backend, and a Python MCP server. The frontend handles the chat UI, while the backend coordinates real-time communication and MCP interactions.

# Development
npm run dev              # Start both frontend and backend
npm run dev:frontend     # Start only frontend
npm run dev:backend      # Start only backend

# Building
npm run build            # Build both
npm run build:frontend   # Build frontend only
npm run build:backend    # Build backend only

# Testing
npm run test             # Run all tests

Notes on MCP server configuration from the source

You can run a local MCP server instance using Docker. The following explicit command shows how to start the MCP server with Docker and environment variables for connecting to a remote macOS machine.

{
  "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"
      ]
    }
  }
}

Available tools

remote_macos_get_screen

Connect to a remote macOS machine and capture a screenshot of the remote desktop using configured environment details.

remote_macos_send_keys

Send keyboard input to a remote macOS machine using the established connection details.

remote_macos_mouse_move

Move the mouse cursor on the remote macOS machine, with automatic coordinate scaling.

remote_macos_mouse_click

Click at specified coordinates on the remote macOS machine with coordinate scaling.

remote_macos_mouse_double_click

Double-click at specified coordinates on the remote macOS machine with coordinate scaling.

remote_macos_mouse_scroll

Scroll on the remote macOS machine at given coordinates with coordinate scaling.

remote_macos_open_application

Open or activate an application on the remote macOS machine and return its PID.

remote_macos_mouse_drag_n_drop

Drag from a start point to an end point on the remote macOS machine with coordinate scaling.