macOS Remote Control

by senseisven

Not rated
GitHub

About

A Python server for remote macOS control via VNC, featuring an AI-powered chat web interface.

Details

Author
senseisven
Categories
Productivity, Other, Automation, AI

Setup

Install macOS Remote Control in your MCP client (Claude Desktop, Cursor, Windsurf, and others).

Repository: https://github.com/senseisven/mcp_macos

Follow the installation instructions in the repository README, then restart your MCP client.

MCP Remote macOS Control Server + AI Chat Web App

The first open-source MCP server that enables AI to fully control remote macOS systems, now with a web-based chat interface.
- MCP Server- Python-based server for remote macOS control via VNC
- AI Chat Web App- Modern web interface for chatting with AI to control your Mac

- Docker Desktop installed
- Node.js 18+ installed
- A Mac with Screen Sharing enabled (can be the same machine)

git clone <repository-url> cd mcp_macos # Install root dependencies npm install # Install frontend and backend dependencies npm run install:all
# Copy example environment file cp backend/.env.example backend/.env # Edit backend/.env with your settings: # - MACOS_HOST=localhost (for local control) # - MACOS_PASSWORD=your_vnc_password # - OPENAI_API_KEY=your_openai_api_key

- Open System Preferences > Sharing
- Enable "Screen Sharing"
- Set a VNC password when prompted

# 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

- Openhttp://localhost:3000in your browser
- Wait for connection to establish
- Try commands like:

- "Take a screenshot"
- "Open Safari"
- "Click on the Dock"
- "Type hello world"

mcp_macos/ ├── frontend/ # Next.js React frontend │ ├── src/ │ │ ├── components/ # Chat interface components │ │ ├── hooks/ # Socket.IO and state management │ │ ├── stores/ # Zustand state stores │ │ └── types/ # TypeScript definitions ├── backend/ # Node.js Express backend │ ├── src/ │ │ ├── services/ # MCP client, LLM service, chat service │ │ ├── config/ # Environment configuration │ │ └── utils/ # Logging and utilities └── src/ # Original Python MCP server ├── mcp_remote_macos_use/ ├── action_handlers.py └── vnc_client.py
# 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
Browser ←→ Frontend (Next.js) ←→ Backend (Node.js) ←→ MCP Server (Python) ←→ macOS WebSocket/HTTP Socket.IO/REST Docker/stdio VNC

- Frontend: Modern React app with real-time chat interface
- Backend: Express.js server with Socket.IO for real-time communication
- LLM Integration: OpenAI GPT-4 for natural language understanding
- MCP Client: Communicates with Python MCP server via Docker
- macOS Control: VNC-based control of local or remote Macs

You: "Take a screenshot" AI: "Here's a screenshot of your Mac desktop:" [shows image] You: "Click on Safari in the dock" AI: "I'll click on Safari in the dock for you" [clicks Safari] You: "Open a new tab and go to apple.com" AI: "Opening a new tab and navigating to apple.com" [executes commands]

- Only use with Macs you own or have explicit permission to control
- VNC passwords are transmitted securely
- LLM API keys are stored server-side only
- All actions are logged for debugging

The original Python MCP server functionality remains fully intact. See below for the original documentation about using it directly with Claude Desktop.

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.

-

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

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

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
- Performance Optimization- Match speed of Ubuntu desktop alternatives
- Apple Scripts Generation- Reduce execution time while maintaining flexibility
- VNC Cursor Visibility- Improve debugging and demo experience

- 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

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.

- 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

- 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

- 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

- Enable Screen Sharing on MacOsIf 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 DesktopYou 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" ] } } }

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:
- Set up a LiveKit server or use LiveKit Cloud
- Configure the LiveKit environment variables as shown in the configuration example above

# Clone the repository git clone https://github.com/yourusername/mcp-remote-macos-use.git cd mcp-remote-macos-use
# Build the Docker image docker build -t mcp-remote-macos-use .

To publish the Docker image for multiple platforms, you can use thedocker buildxcommand. Follow these steps:
-

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

Build and push the image for multiple platforms:

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

Verify the image is available for the specified platforms:

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

The server provides Remote MacOs functionality through MCP tools.

The server provides the following tools for remote macOS control:

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

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

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

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

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

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

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

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.

- Authentication Support:

- Only Apple Authentication (protocol 30) is supported

https://support.apple.com/guide/remote-desktop/encrypt-network-data-apdfe8e386b/machttps://cafbit.com/post/apple_remote_desktop_quirks/

We only support 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.

Here's the information converted to a markdown table:

Always use secure, authenticated connections when accessing remote remote MacOs machines. This tool should only be used with servers you trust and have permission to access.

Read-only MCP endpoint for a managed dedicated Mac mini AI operator setup service with public pricing and a 10-founder-install queue.

An open-source MCP server that allows AI to fully control a remote macOS system.

Let Claude control your Mac — 12 typed tools for windows, menus, keyboard, clipboard, browser tabs

Enables LLM clients to interact with macOS applications through AppleScript. Built using the @beyondbetter/bb-mcp-server library, this server provides safe, controlled execution of predefined scripts with optional support for arbitrary script execution.

MCP server for the Computer-Use Agent (CUA), allowing you to run CUA through Claude Desktop or other MCP clients.

Interact with task, doc, and project data in Dart, an AI-native project management tool

Create notes, search, & think with your Fabric AI workspace

Great Question is an Agentic UX research platform for product builders. Its MCP lets AI agents create studies directly from any AI tool, surface insights, find the right research candidates, and query your entire research repository.

Magica is your all-in-one AI platform, offering 2500+ cutting-edge tools under a single subscription.

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.