macOS Remote Control

Un servidor Python para control remoto de macOS a través de VNC, con una interf

Documentación

Servidor MCP de Control Remoto de macOS + Aplicación Web de Chat con IA

El primer servidor MCP de código abierto que permite a la IA controlar completamente sistemas macOS remotos, ahora con una interfaz web de chat.

Este proyecto proporciona ambos:

Servidor MCP - Servidor basado en Python para control remoto de macOS a través de VNC
Aplicación Web de Chat con IA - Interfaz web moderna para chatear con IA y controlar tu Mac

🚀 Inicio Rápido para la Aplicación Web

Requisitos Previos

Docker Desktop instalado
Node.js 18+ instalado
Un Mac con Compartir Pantalla habilitado (puede ser la misma máquina)

1. Clonar y Configurar

git clone <repository-url>
cd mcp_macos

# Install root dependencies
npm install

# Install frontend and backend dependencies
npm run install:all

2. Configurar el Entorno

# 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. Habilitar Compartir Pantalla (macOS)

Abre Preferencias del Sistema > Compartir
Habilita "Compartir Pantalla"
Establece una contraseña VNC cuando se te solicite

4. Ejecutar la Aplicación

# 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. ¡Abrir y Chatear!

Abre http://localhost:3000 en tu navegador
Espera a que se establezca la conexión
Prueba comandos como:
- "Toma una captura de pantalla"
- "Abre Safari"
- "Haz clic en el Dock"
- "Escribe hola mundo"

📁 Estructura del Proyecto

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

🔧 Comandos de Desarrollo

# 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

🎯 Arquitectura

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

🛠️ Cómo Funciona

Frontend: Aplicación React moderna con interfaz de chat en tiempo real
Backend: Servidor Express.js con Socket.IO para comunicación en tiempo real
Integración LLM: OpenAI GPT-4 para comprensión del lenguaje natural
Cliente MCP: Se comunica con el servidor MCP de Python a través de Docker
Control de macOS: Control basado en VNC de Macs locales o remotos

🎮 Ejemplos de Interacciones

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]

🔒 Notas de Seguridad

Úsalo solo con Macs que poseas o para los cuales tengas permiso explícito de control
Las contraseñas VNC se transmiten de forma segura
Las claves API de LLM se almacenan solo en el lado del servidor
Todas las acciones se registran para depuración

📚 Documentación Original del Servidor MCP

La funcionalidad original del servidor MCP de Python permanece completamente intacta. Consulta a continuación la documentación original sobre cómo usarlo directamente con Claude Desktop.

Documentación Original del Servidor MCP

El primer servidor MCP de código abierto que permite a la IA controlar completamente sistemas macOS remotos.

Una alternativa directa a OpenAI Operator, optimizada específicamente para agentes de IA autónomos con capacidades completas de escritorio, sin requerir instalación de software adicional.

Demostraciones

Investiga Twitter y Publica en Twitter(https://www.youtube.com/watch?v=--QHz2jcvcs)
Usa CapCut para crear un video corto de destacados(https://www.youtube.com/watch?v=RKAqiNoU8ec)
Reclutador de IA: Recopilación automatizada de información de candidatos, calificación de solicitudes y envío de sesiones de selección usando la aplicación Mail
Pasante de Marketing de IA: Interacción en LinkedIn - seguimiento, likes y comentarios automatizados con usuarios relevantes
Pasante de Marketing de IA: Interacción en Twitter - seguimiento, likes y comentarios automatizados con usuarios relevantes

Lista de Tareas Pendientes (Priorizada)

Optimización del Rendimiento - Igualar la velocidad de las alternativas de escritorio Ubuntu
Generación de Scripts de Apple - Reducir el tiempo de ejecución manteniendo la flexibilidad
Visibilidad del Cursor VNC - Mejorar la experiencia de depuración y demostración

¡Aceptamos contribuciones!

Características

Sin Costos Adicionales de API: Procesamiento de pantalla gratuito con tu plan existente de Claude Pro
Configuración Mínima: Solo habilita Compartir Pantalla en el Mac objetivo – no se necesita software adicional
Compatibilidad Universal: Funciona con todas las versiones de macOS, actuales y futuras

Por Qué Lo Construimos

Experiencia Nativa de macOS Sin Compromisos

El ecosistema nativo de macOS sigue siendo incomparable en experiencia de usuario hoy en día y continuará siendo el estándar de oro durante años. Aquí es donde las capacidades humanas realmente prosperan, y ahora tu IA puede operar en este entorno con la misma fluidez.

Arquitectura Abierta Por Diseño

Compatibilidad Universal con LLM: Funciona con cualquier Cliente MCP de tu elección
Flexibilidad de Modelos: Integración perfecta con OpenAI, Anthropic o cualquier otro proveedor de LLM
Integración a Prueba de Futuro: Diseñado para evolucionar con el ecosistema MCP

Despliegue Sin Esfuerzo

Cero Configuración en Máquinas Objetivo: Sin aplicaciones en segundo plano ni agentes necesarios en macOS
Compartir Pantalla es Todo lo que Necesitas: Controla cualquier Mac con Compartir Pantalla habilitado
Elimina la Complejidad del Backend: A diferencia de otras soluciones que requieren ejecutar aplicaciones Python o servicios en segundo plano

Proceso de Arranque Simplificado

Aprovecha la Interfaz Pulida de Claude Desktop: Sin necesidad de interfaces Python estilo desarrollador
Experiencia de Usuario Intuitiva: Interactúa con tu Mac controlado por IA a través de una interfaz familiar y fácil de usar
Productividad Instantánea: Comienza a trabajar inmediatamente sin problemas de configuración

Arquitectura

Instalación

Habilitar Compartir Pantalla en macOS Si alquilas un Mac de macstadium.com, puedes omitir este paso
Conectarte a tu macOS remoto
Instalar Docker Desktop para Mac local
Agregar este servidor MCP a Claude Desktop Puedes configurar Claude Desktop para usar la imagen Docker agregando lo siguiente a tu configuración de Claude:

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

Soporte WebRTC a través de LiveKit

Este servidor ahora incluye soporte WebRTC mediante la integración de LiveKit, lo que permite:

Compartir pantalla en tiempo real con baja latencia
Rendimiento y capacidad de respuesta mejorados
Mejor eficiencia de red en comparación con el VNC tradicional
Adaptación automática de calidad según las condiciones de la red

Para usar las funciones WebRTC, necesitarás:

Configurar un servidor LiveKit o usar LiveKit Cloud
Configurar las variables de entorno de LiveKit como se muestra en el ejemplo de configuración anterior

Instrucciones para Desarrolladores

Clonar el repositorio

# Clone the repository
git clone https://github.com/yourusername/mcp-remote-macos-use.git
cd mcp-remote-macos-use

Construir la Imagen Docker

# Build the Docker image
docker build -t mcp-remote-macos-use .

Publicación Multiplataforma

Para publicar la imagen Docker para múltiples plataformas, puedes usar el comando docker buildx. Sigue estos pasos:

Crear una nueva instancia de builder (si aún no lo has hecho):
```
docker buildx create --use
```

Construir y publicar la imagen para múltiples plataformas:

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

Verificar que la imagen esté disponible para las plataformas especificadas:
```
docker buildx imagetools inspect buryhuang/mcp-remote-macos-use:latest
```

Uso

El servidor proporciona funcionalidad de macOS remoto a través de herramientas MCP.

Especificaciones de Herramientas

El servidor proporciona las siguientes herramientas para el control remoto de macOS:

remote_macos_get_screen

Conectarse a una máquina macOS remota y obtener una captura de pantalla del escritorio remoto. Utiliza variables de entorno para los detalles de conexión.

remote_macos_send_keys

Enviar entrada de teclado a una máquina macOS remota. Utiliza variables de entorno para los detalles de conexión.

remote_macos_mouse_move

Mover el cursor del mouse a coordenadas especificadas en una máquina macOS remota, con escalado automático de coordenadas. Utiliza variables de entorno para los detalles de conexión.

remote_macos_mouse_click

Realizar un clic del mouse en coordenadas especificadas en una máquina macOS remota, con escalado automático de coordenadas. Utiliza variables de entorno para los detalles de conexión.

remote_macos_mouse_double_click

Realizar un doble clic del mouse en coordenadas especificadas en una máquina macOS remota, con escalado automático de coordenadas. Utiliza variables de entorno para los detalles de conexión.

remote_macos_mouse_scroll

Realizar un desplazamiento del mouse en coordenadas especificadas en una máquina macOS remota, con escalado automático de coordenadas. Utiliza variables de entorno para los detalles de conexión.

remote_macos_open_application

Abre/activa una aplicación y devuelve su PID para interacciones posteriores.

remote_macos_mouse_drag_n_drop

Realizar una operación de arrastre del mouse desde un punto de inicio y soltar en un punto final en una máquina macOS remota, con escalado automático de coordenadas.

Todas las herramientas utilizan las variables de entorno configuradas durante la instalación en lugar de requerir parámetros de conexión.

Limitaciones

Soporte de Autenticación:
- Solo se admite Autenticación de Apple (protocolo 30)

Nota de Seguridad

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

Solo admitimos el protocolo 30, que utiliza el protocolo de acuerdo de claves Diffie-Hellman con un primo de 512 bits. Este protocolo es utilizado por macOS 11 a macOS 12 cuando se comunica con clientes OS X 10.11 o anteriores.

Aquí está la información convertida a una tabla de markdown:

Versión de macOS que ejecuta Remote Desktop	Versión del cliente macOS	Autenticación	Control y Observación	Copiar elementos o instalar paquete	Todas las demás tareas	Versión del Protocolo
macOS 13	macOS 13	Claves de host RSA de 2048 bits	Claves de host RSA de 2048 bits	Claves de host RSA de 2048 bits para autenticar, luego AES de 128 bits	Claves de host RSA de 2048 bits	36
macOS 13	macOS 10.12	Protocolo Secure Remote Password (SRP) solo para local. Diffie-Hellman (DH) si está vinculado a LDAP o el servidor macOS es versión 10.11 o anterior	SRP o DH, AES de 128 bits	SRP o DH para autenticar, luego AES de 128 bits	Claves de host RSA de 2048 bits	35
macOS 11 a macOS 12	macOS 10.12 a macOS 13	Protocolo Secure Remote Password (SRP) solo para local, Diffie-Hellman si está vinculado a LDAP	SRP o DH de 1024 bits, AES de 128 bits	Claves de host RSA de 2048 bits macOS 13 a macOS 10.13	Claves de host RSA de 2048 bits macOS 10.13 o posterior	33
macOS 11 a macOS 12	OS X 10.11 o anterior	DH de 1024 bits	DH de 1024 bits, AES de 128 bits	Protocolo de acuerdo de claves Diffie-Hellman con un primo de 512 bits	Protocolo de acuerdo de claves Diffie-Hellman con un primo de 512 bits	30

Utiliza siempre conexiones seguras y autenticadas al acceder a máquinas macOS remotas. Esta herramienta solo debe usarse con servidores en los que confíes y tengas permiso para acceder.

Licencia

Consulta el archivo LICENSE para más detalles.