OP
AI & ML

Open-Source MCP Server for Autonomous macOS Agents

Host an open-source MCP server to run remote macOS machines as autonomous agents with a full desktop experience, replacing OpenAI Operator

View on GitHub
Quick Install
npx -y @baryhuang/mcp-remote-macos-use

Overview

This project provides an open-source MCP (Model Context Protocol) server designed to expose remote macOS machines as autonomous agents with a full desktop experience. By hosting your own MCP server you can run macOS machines under programmatic control (LLM-driven agents), stream their desktops, transfer files, and automate GUI or CLI workflows without relying on hosted operator services. It is positioned as an open alternative to closed “operator” systems, enabling teams to maintain control over their data, network, and macOS fleet.

The server coordinates agent registration, session brokering, and tool access (desktop streaming, shell, file transfer, etc.). Agents run on individual macOS hosts and connect back to the MCP server; clients (LLMs or orchestrators implementing MCP) then request agent actions through the server. This separation makes it easier to scale macOS automation, instrument remote debugging, or build LLM-based assistants that need real macOS desktops.

Features

  • Agent registration and lifecycle management for remote macOS hosts
  • Desktop streaming (VNC / WebRTC) for interactive GUI access
  • Remote shell and AppleScript automation for macOS-native control
  • File upload/download and artifact collection
  • API key / token-based authentication for secure agent-client interactions
  • Self-hosted deployment: run the server in your environment (Docker Compose example included)
  • Logs and basic observability for sessions and agent health
  • Designed to be compatible with MCP-aware LLM clients and workflows

Installation / Configuration

Prerequisites:

  • Docker & Docker Compose (or equivalent container runtime)
  • Publicly reachable hostname or VPN for agents to reach the server
  • macOS hosts to run the agent (Big Sur / Monterey / Ventura and later recommended)

Quick start (Docker Compose):

  1. Clone the repository
git clone https://github.com/baryhuang/mcp-remote-macos-use.git
cd mcp-remote-macos-use
  1. Create a .env file (example)
# .env
MCP_HOSTNAME=example.yourdomain.com
MCP_HTTP_PORT=8080
MCP_HTTPS_PORT=443
MCP_ADMIN_KEY=supersecretadmintoken
MCP_AGENT_SECRET=shared-agent-secret
WEBRTC_CERT=/path/to/fullchain.pem
WEBRTC_KEY=/path/to/privkey.pem
  1. Example docker-compose.yml
version: "3.8"
services:
  mcp-server:
    image: ghcr.io/baryhuang/mcp-server:latest
    restart: unless-stopped
    env_file: .env
    ports:
      - "${MCP_HTTP_PORT}:8080"
      - "${MCP_HTTPS_PORT}:8443"
    volumes:
      - ./data:/var/lib/mcp
      - ./certs:/certs
  1. Launch
docker-compose up -d
  1. Register macOS agents
  • Generate an agent registration token (via admin endpoint or .env)
  • On the macOS host, run the provided install/agent script and supply the token:
curl -fsSL https://example.yourdomain.com/install-agent.sh | bash -s -- --token YOUR_REGISTRATION_TOKEN

The agent will establish an outbound connection to the MCP server and appear in the admin UI / API.

Notes

  • If your server sits behind a reverse proxy, map ports and TLS correctly and keep the MCP_HOSTNAME reachable by agents.
  • Use strong tokens and network controls for production use.

Available Resources

  • Desktop streaming: WebRTC or VNC bridges depending on network and latency requirements
  • Remote shell: secure interactive shell sessions executed on the macOS agent
  • AppleScript / osascript: execute GUI automation and native macOS commands
  • File transfer: upload/download files between client and agent
  • Session logs: store activity logs and artifacts for audits and debugging

Refer to the repo for platform-specific agent installers and scripts for configuring screen sharing, accessibility permissions, and persistent agent services on macOS.

Use Cases

  • Continuous Integration for macOS-only builds
    Example: An LLM orchestrator instructs an agent to run xcodebuild, collect the .ipa, and upload build artifacts to an internal artifact store. Steps: register macOS agent → trigger build session → stream logs → download artifacts.

  • Reproducible bug triage and remote debugging
    Example: A support engineer uses an MCP client to spawn a full desktop session on customer-similar hardware, reproduces an issue via GUI steps, records video, and collects system logs for the issue tracker.

  • Automated GUI workflows and testing
    Example: Run end-to-end tests that require interacting with Finder or other GUI apps (installer flows, UI acceptance tests). The agent runs scripted AppleScript sequences driven by an LLM or test orchestrator.

  • LLM-based macOS assistant (replacement for operator services)
    Example: An organization runs its own LLM-based assistant that needs to control macOS desktops to perform administrative tasks. Hosting your own MCP server keeps data and credentials in your environment rather than an external operator.

Next steps

  • Review the repository for agent installer details and permissions required on macOS (Accessibility, Screen Recording, etc.).
  • Harden authentication and network access (mutual TLS, firewall rules).
  • Integrate with your MCP-aware LLM client or toolchain by following the server’s API docs in the repo.

Repository: https://github.com/baryhuang/mcp-remote-macos-use

Tags:ai-ml