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.

This project provides both:

1. MCP Server - Python-based server for remote macOS control via VNC
2. AI Chat Web App - Modern web interface for chatting with AI to control your Mac

🚀 Quick Start for Web App

Prerequisites

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

1. Clone and Setup

git clone 
cd mcp_macos

# Install root dependencies
npm install

# Install frontend and backend dependencies
npm run install:all

2. Configure Environment

# 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

3. Enable Screen Sharing (macOS)

1. Open System Preferences > Sharing
2. Enable “Screen Sharing”
3. 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!

1. Open http://localhost:3000 in your browser
2. Wait for connection to establish
3. Try commands like:
   • “Take a screenshot”
   • “Open Safari”
   • “Click on the Dock”
   • “Type hello world”

📁 Project Structure

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 Commands

# 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

🎯 Architecture

Browser ←→ Frontend (Next.js) ←→ Backend (Node.js) ←→ MCP Server (Python) ←→ macOS
         WebSocket/HTTP        Socket.IO/REST      Docker/stdio         VNC

🛠️ How It Works

1. Frontend: Modern React app with real-time chat interface
2. Backend: Express.js server with Socket.IO for real-time communication