macOS Remote Control

Um servidor Python para controle remoto de macOS via VNC, com uma interface web de chat alimentada por IA.

Documentação

Servidor MCP de Controle Remoto macOS + Aplicativo Web de Chat com IA

O primeiro servidor MCP de código aberto que permite à IA controlar totalmente sistemas macOS remotos, agora com uma interface web de chat.

Este projeto fornece ambos:

Servidor MCP - Servidor baseado em Python para controle remoto de macOS via VNC
Aplicativo Web de Chat com IA - Interface web moderna para conversar com a IA e controlar seu Mac

🚀 Início Rápido para o Aplicativo Web

Pré-requisitos

Docker Desktop instalado
Node.js 18+ instalado
Um Mac com Compartilhamento de Tela ativado (pode ser a mesma máquina)

1. Clonar e Configurar

git clone <repository-url>
cd mcp_macos

# Install root dependencies
npm install

# Install frontend and backend dependencies
npm run install:all

2. Configurar o Ambiente

# 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. Ativar o Compartilhamento de Tela (macOS)

Abra Preferências do Sistema > Compartilhamento
Ative "Compartilhamento de Tela"
Defina uma senha VNC quando solicitado

4. Executar o Aplicativo

# 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 e Conversar!

Abra http://localhost:3000 no seu navegador
Aguarde a conexão ser estabelecida
Experimente comandos como:
- "Tirar uma captura de tela"
- "Abrir o Safari"
- "Clicar no Dock"
- "Digitar olá mundo"

📁 Estrutura do Projeto

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 Desenvolvimento

# 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

🎯 Arquitetura

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

🛠️ Como Funciona

Frontend: Aplicativo React moderno com interface de chat em tempo real
Backend: Servidor Express.js com Socket.IO para comunicação em tempo real
Integração com LLM: OpenAI GPT-4 para compreensão de linguagem natural
Cliente MCP: Comunica-se com o servidor MCP Python via Docker
Controle macOS: Controle baseado em VNC de Macs locais ou remotos

🎮 Exemplos de Interações

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 Segurança

Use apenas com Macs que você possui ou tem permissão explícita para controlar
Senhas VNC são transmitidas de forma segura
Chaves de API do LLM são armazenadas apenas no lado do servidor
Todas as ações são registradas para depuração

📚 Documentação Original do Servidor MCP

A funcionalidade original do servidor MCP Python permanece totalmente intacta. Veja abaixo a documentação original sobre como usá-lo diretamente com o Claude Desktop.

Documentação Original do Servidor MCP

O primeiro servidor MCP de código aberto que permite à IA controlar totalmente sistemas macOS remotos.

Uma alternativa direta ao OpenAI Operator, otimizada especificamente para agentes de IA autônomos com capacidades completas de desktop, sem exigir instalação de software adicional.

Demonstrações

Pesquisar no Twitter e Publicar no Twitter(https://www.youtube.com/watch?v=--QHz2jcvcs)
Usar CapCut para criar vídeo curto de destaques(https://www.youtube.com/watch?v=RKAqiNoU8ec)
Recrutador de IA: Coleta automatizada de informações de candidatos, qualificação de inscrições e envio de sessões de triagem usando o aplicativo Mail
Estagiário de Marketing de IA: Engajamento no LinkedIn - seguir, curtir e comentar automaticamente com usuários relevantes
Estagiário de Marketing de IA: Engajamento no Twitter - seguir, curtir e comentar automaticamente com usuários relevantes

Lista de Tarefas (Priorizada)

Otimização de Desempenho - Igualar a velocidade das alternativas de desktop Ubuntu
Geração de Apple Scripts - Reduzir o tempo de execução mantendo a flexibilidade
Visibilidade do Cursor VNC - Melhorar a experiência de depuração e demonstração

Aceitamos contribuições!

Recursos

Sem Custos Adicionais de API: Processamento de tela gratuito com seu plano Claude Pro existente
Configuração Mínima: Basta ativar o Compartilhamento de Tela no Mac de destino – nenhum software adicional é necessário
Compatibilidade Universal: Funciona com todas as versões do macOS, atuais e futuras

Por Que Construímos Isso

Experiência macOS Nativa Sem Compromissos

O ecossistema nativo do macOS permanece incomparável em experiência do usuário hoje e continuará sendo o padrão ouro por muitos anos. É onde as capacidades humanas realmente prosperam, e agora sua IA pode operar neste ambiente com a mesma fluência.

Arquitetura Aberta por Design

Compatibilidade Universal com LLM: Funcione com qualquer Cliente MCP de sua escolha
Flexibilidade de Modelo: Integre-se perfeitamente com OpenAI, Anthropic ou qualquer outro provedor de LLM
Integração à Prova do Futuro: Projetado para evoluir com o ecossistema MCP

Implantação Sem Esforço

Zero Configuração nas Máquinas de Destino: Sem aplicativos em segundo plano ou agentes necessários no macOS
Compartilhamento de Tela é Tudo que Você Precisa: Controle qualquer Mac com Compartilhamento de Tela ativado
Elimine a Complexidade do Backend: Diferente de outras soluções que exigem executar aplicativos Python ou serviços em segundo plano

Processo de Inicialização Simplificado

Aproveite a Interface Polida do Claude Desktop: Sem necessidade de interfaces Python estilo desenvolvedor
Experiência de Usuário Intuitiva: Interaja com seu Mac controlado por IA através de uma interface familiar e amigável
Produtividade Imediata: Comece a trabalhar imediatamente sem complicações de configuração

Arquitetura

Instalação

Ativar Compartilhamento de Tela no macOS Se você alugar um Mac da macstadium.com, pode pular esta etapa
Conectar ao seu macOS remoto
Instalar Docker Desktop para Mac local
Adicionar este servidor MCP ao Claude Desktop Você pode configurar o Claude Desktop para usar a imagem Docker adicionando o seguinte à sua configuração do 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"
      ]
    }
  }
}

Suporte WebRTC via LiveKit

Este servidor agora inclui suporte WebRTC através da integração com LiveKit, permitindo:

Compartilhamento de tela em tempo real com baixa latência
Desempenho e capacidade de resposta melhorados
Melhor eficiência de rede comparado ao VNC tradicional
Adaptação automática de qualidade com base nas condições da rede

Para usar os recursos WebRTC, você precisará:

Configurar um servidor LiveKit ou usar o LiveKit Cloud
Configurar as variáveis de ambiente do LiveKit conforme mostrado no exemplo de configuração acima

Instruções para Desenvolvedores

Clonar o repositório

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

Construindo a Imagem Docker

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

Publicação Multi-Plataforma

Para publicar a imagem Docker para múltiplas plataformas, você pode usar o comando docker buildx. Siga estes passos:

Criar uma nova instância de builder (se ainda não tiver):
```
docker buildx create --use
```

Construir e enviar a imagem para múltiplas plataformas:

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

Verificar se a imagem está disponível para as plataformas especificadas:
```
docker buildx imagetools inspect buryhuang/mcp-remote-macos-use:latest
```

Uso

O servidor fornece funcionalidade de macOS Remoto através de ferramentas MCP.

Especificações das Ferramentas

O servidor fornece as seguintes ferramentas para controle remoto de macOS:

remote_macos_get_screen

Conecta a uma máquina macOS remota e obtém uma captura de tela da área de trabalho remota. Usa variáveis de ambiente para detalhes de conexão.

remote_macos_send_keys

Envia entrada de teclado para uma máquina macOS remota. Usa variáveis de ambiente para detalhes de conexão.

remote_macos_mouse_move

Move o cursor do mouse para coordenadas especificadas em uma máquina macOS remota, com dimensionamento automático de coordenadas. Usa variáveis de ambiente para detalhes de conexão.

remote_macos_mouse_click

Realiza um clique do mouse em coordenadas especificadas em uma máquina macOS remota, com dimensionamento automático de coordenadas. Usa variáveis de ambiente para detalhes de conexão.

remote_macos_mouse_double_click

Realiza um clique duplo do mouse em coordenadas especificadas em uma máquina macOS remota, com dimensionamento automático de coordenadas. Usa variáveis de ambiente para detalhes de conexão.

remote_macos_mouse_scroll

Realiza uma rolagem do mouse em coordenadas especificadas em uma máquina macOS remota, com dimensionamento automático de coordenadas. Usa variáveis de ambiente para detalhes de conexão.

remote_macos_open_application

Abre/ativa um aplicativo e retorna seu PID para interações adicionais.

remote_macos_mouse_drag_n_drop

Realiza uma operação de arrastar do ponto inicial e soltar no ponto final em uma máquina macOS remota, com dimensionamento automático de coordenadas.

Todas as ferramentas usam as variáveis de ambiente configuradas durante a instalação em vez de exigir parâmetros de conexão.

Limitações

Suporte de Autenticação:
- Apenas Autenticação Apple (protocolo 30) é suportada

Nota de Segurança

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

Suportamos apenas o protocolo 30, que usa o protocolo de acordo de chave Diffie-Hellman com um primo de 512 bits. Este protocolo é usado pelo macOS 11 ao macOS 12 ao se comunicar com clientes OS X 10.11 ou anteriores.

Aqui estão as informações convertidas em uma tabela markdown:

Versão do macOS executando o Remote Desktop	Versão do cliente macOS	Autenticação	Controle e Observação	Copiar itens ou instalar pacote	Todas as outras tarefas	Versão do Protocolo
macOS 13	macOS 13	Chaves de host RSA de 2048 bits	Chaves de host RSA de 2048 bits	Chaves de host RSA de 2048 bits para autenticar, depois AES de 128 bits	Chaves de host RSA de 2048 bits	36
macOS 13	macOS 10.12	Protocolo Secure Remote Password (SRP) apenas para local. Diffie-Hellman (DH) se vinculado a LDAP ou servidor macOS versão 10.11 ou anterior	SRP ou DH, AES de 128 bits	SRP ou DH para autenticar, depois AES de 128 bits	Chaves de host RSA de 2048 bits	35
macOS 11 ao macOS 12	macOS 10.12 ao macOS 13	Protocolo Secure Remote Password (SRP) apenas para local, Diffie-Hellman se vinculado a LDAP	SRP ou DH de 1024 bits, AES de 128 bits	Chaves de host RSA de 2048 bits macOS 13 ao macOS 10.13	Chaves de host RSA de 2048 bits macOS 10.13 ou posterior	33
macOS 11 ao macOS 12	OS X 10.11 ou anterior	DH de 1024 bits	DH de 1024 bits, AES de 128 bits	Protocolo de acordo de chave Diffie-Hellman com um primo de 512 bits	Protocolo de acordo de chave Diffie-Hellman com um primo de 512 bits	30

Sempre use conexões seguras e autenticadas ao acessar máquinas macOS remotas. Esta ferramenta deve ser usada apenas com servidores em que você confia e tem permissão para acessar.

Licença

Consulte o arquivo LICENSE para detalhes.