Windows Control

Controle programático sobre operações do sistema Windows, incluindo mouse, teclado, gerenciamento de janelas e captura de tela usando nut.js.

GitHub
332
Experimente este MCPPatrocinado

Documentação

MCPControl

MCPControl Logo

Latest Release

Servidor de controle do Windows para o Model Context Protocol, fornecendo controle programático sobre operações do sistema, incluindo mouse, teclado, gerenciamento de janelas e funcionalidade de captura de tela.

Nota: Este projeto atualmente suporta apenas Windows.

🔥 Por que MCPControl?

O MCPControl preenche a lacuna entre modelos de IA e sua área de trabalho, permitindo controle seguro e programático de:

  • 🖱️ Movimentos e cliques do mouse
  • ⌨️ Entrada de teclado e atalhos
  • 🪟 Gerenciamento de janelas
  • 📸 Captura e análise de tela
  • 📋 Operações de área de transferência

🔌 Início Rápido

Pré-requisitos

  1. Instale as Ferramentas de Build (incluindo carga de trabalho VC++)

    # Run as Administrator - may take a few minutes to complete
winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

  2. Instale o Python (se ainda não estiver instalado)

    # Install Python (required for node-gyp)
winget install Python.Python.3.12

  3. Instale o Node.js

    # Install latest LTS version
winget install OpenJS.NodeJS

Instalação

  1. Instale o Pacote MCPControl 
    npm install -g mcp-control

Configuração

O MCPControl funciona melhor em uma máquina virtual com resolução 1280x720 para precisão ideal de cliques.

Configure seu cliente Claude para conectar ao MCPControl via transporte SSE:

Opção 1: Conexão SSE Direta

Para conectar a um servidor MCPControl em execução em uma VM ou máquina remota:

{
  "mcpServers": {
    "MCPControl": {
      "transport": "sse",
      "url": "http://192.168.1.100:3232/mcp"
    }
  }
}

Substitua 192.168.1.100:3232 pelo endereço IP e porta do seu servidor.

Opção 2: Inicialização Local com SSE

Para iniciar o MCPControl localmente com transporte SSE:

{
  "mcpServers": {
    "MCPControl": {
      "command": "mcp-control",
      "args": ["--sse"]
    }
  }
}

Iniciando o Servidor

Primeiro, inicie o servidor MCPControl na sua VM ou máquina local:

mcp-control --sse

O servidor exibirá:

  • Interfaces de rede disponíveis e seus endereços IP
  • O número da porta (padrão: 3232)
  • Mensagens de status de conexão

Exemplo de Configuração de VM

  1. Inicie sua VM Windows com resolução 1280x720
  2. Instale o MCPControl na VM: 
    npm install -g mcp-control
  3. Execute o servidor com transporte SSE: 
    mcp-control --sse
  4. Anote o endereço IP da VM (ex.: 192.168.1.100)
  5. Configure o Claude com a URL SSE: 
    {
  "mcpServers": {
    "MCPControl": {
      "transport": "sse",
      "url": "http://192.168.1.100:3232/mcp"
    }
  }
}
  6. Reinicie o Claude e o MCPControl aparecerá no seu menu MCP!

🔧 Opções de CLI

O MCPControl suporta várias flags de linha de comando para configurações avançadas:

# Run with SSE transport on default port (3232)
mcp-control --sse

# Run with SSE on custom port
mcp-control --sse --port 3000

# Run with HTTPS/TLS (required for production deployments)
mcp-control --sse --https --cert /path/to/cert.pem --key /path/to/key.pem

# Run with HTTPS on custom port
mcp-control --sse --https --port 8443 --cert /path/to/cert.pem --key /path/to/key.pem

Argumentos de Linha de Comando

  • --sse - Habilita transporte SSE (Server-Sent Events) para acesso de rede
  • --port [number] - Especifica porta personalizada (padrão: 3232)
  • --https - Habilita HTTPS/TLS (obrigatório para implantações remotas conforme especificação MCP)
  • --cert [path] - Caminho para o arquivo de certificado TLS (obrigatório com --https)
  • --key [path] - Caminho para o arquivo de chave privada TLS (obrigatório com --https)

Nota de Segurança

De acordo com a especificação MCP, HTTPS é obrigatório para todos os transportes baseados em HTTP em ambientes de produção. Ao implantar o MCPControl para acesso remoto, sempre use a flag --https com certificados TLS válidos.

🚀 Casos de Uso Populares

Automação Assistida

  • Testes de Aplicativos: Delegue testes repetitivos de UI ao Claude, permitindo que a IA navegue pelos aplicativos e relate problemas
  • Automação de Fluxos de Trabalho: Faça o Claude operar aplicativos em seu nome, lidando com tarefas repetitivas enquanto você se concentra no trabalho criativo
  • Preenchimento de Formulários: Deixe o Claude lidar com tarefas de entrada de dados sob sua supervisão

Experimentação com IA

  • Jogos com IA: Observe o Claude aprender a jogar jogos simples através de feedback visual
  • Raciocínio Visual: Teste a capacidade do Claude de navegar em interfaces visuais e resolver quebra-cabeças visuais
  • Colaboração Humano-IA: Explore novos paradigmas de interação onde o Claude pode ver sua tela e ajudar com tarefas complexas

Desenvolvimento e Testes

  • Integração Entre Aplicativos: Conecte aplicativos que normalmente não se comunicam
  • Framework de Testes de UI: Crie cenários de teste robustos com validação visual
  • Criação de Demonstrações: Automatize a criação de demonstrações de produtos

⚠️ AVISO IMPORTANTE

ESTE SOFTWARE É EXPERIMENTAL E POTENCIALMENTE PERIGOSO

Ao usar este software, você reconhece e aceita que:

  • Dar aos modelos de IA controle direto sobre seu computador através desta ferramenta é inerentemente arriscado
  • Este software pode controlar seu mouse, teclado e outras funções do sistema, o que pode potencialmente causar consequências não intencionais
  • Você está usando este software inteiramente por sua conta e risco
  • Os criadores e contribuidores deste projeto NÃO aceitam NENHUMA responsabilidade por qualquer dano, perda de dados ou outras consequências que possam surgir do uso deste software
  • Esta ferramenta deve ser usada apenas em ambientes controlados com medidas de segurança apropriadas

USE POR SUA CONTA E RISCO

🌟 Recursos

🪟 Gerenciamento de Janelas

  • Listar todas as janelas
  • Obter informações da janela ativa
  • Focar, redimensionar e reposicionar

🖱️ Controle do Mouse

  • Movimento de precisão
  • Operações de clique e arrastar
  • Rolagem e rastreamento de posição

⌨️ Controle do Teclado

  • Entrada de texto e combinações de teclas
  • Controle de pressionar/soltar teclas
  • Funcionalidade de manter tecla pressionada

📸 Operações de Tela

  • Capturas de tela de alta qualidade
  • Detecção de tamanho de tela
  • Captura de janela ativa

🔧 Provedores de Automação

O MCPControl suporta múltiplos provedores de automação para diferentes casos de uso:

  • keysender (padrão) - Automação nativa do Windows com alta confiabilidade
  • powershell - Automação baseada em Windows PowerShell para operações mais simples
  • autohotkey - Scripts AutoHotkey v2 para necessidades avançadas de automação

Configuração do Provedor

Você pode configurar o provedor de automação usando variáveis de ambiente:

# Use a specific provider for all operations
export AUTOMATION_PROVIDER=autohotkey

# Configure AutoHotkey executable path (if not in PATH)
export AUTOHOTKEY_PATH="C:\Program Files\AutoHotkey\v2\AutoHotkey.exe"

Ou use configuração modular para operações específicas:

# Mix and match providers for different operations
export AUTOMATION_KEYBOARD_PROVIDER=autohotkey
export AUTOMATION_MOUSE_PROVIDER=keysender
export AUTOMATION_SCREEN_PROVIDER=keysender  
export AUTOMATION_CLIPBOARD_PROVIDER=powershell

Consulte a documentação específica do provedor:

🛠️ Configuração de Desenvolvimento

Se você está interessado em contribuir ou compilar a partir do código-fonte, consulte CONTRIBUTING.md para instruções detalhadas.

Requisitos de Desenvolvimento

Para compilar este projeto para desenvolvimento, você precisará de:

  1. Sistema operacional Windows (obrigatório para a dependência keysender)
  2. Node.js 18 ou posterior (instale usando o instalador oficial do Windows que inclui ferramentas de build)
  3. Gerenciador de pacotes npm
  4. Ferramentas de build nativas:
    • node-gyp: npm install -g node-gyp
    • cmake-js: npm install -g cmake-js

A dependência keysender depende de módulos nativos específicos do Windows que exigem essas ferramentas de build.

📋 Estrutura do Projeto

  • /src
    • /handlers - Manipuladores de requisição e gerenciamento de ferramentas
    • /tools - Implementações de funcionalidades principais
    • /types - Definições de tipos TypeScript
    • index.ts - Ponto de entrada principal do aplicativo

🔖 Branches do Repositório

  • main - Branch principal de desenvolvimento com os recursos e alterações mais recentes
  • release - Branch de versão estável que espelha a tag estável mais recente (atualmente v0.2.0)

Instalação de Versões

Você pode instalar versões específicas do MCPControl usando npm:

# Install the latest stable release (from release branch)
npm install mcp-control

# Install a specific version
npm install mcp-control@0.1.22

📚 Dependências

🚧 Limitações Conhecidas

  • Operações de minimizar/restaurar janelas não são suportadas atualmente
  • Funções de múltiplas telas podem não funcionar como esperado, dependendo da configuração
  • O utilitário get_screenshot não funciona com a Extensão Cline do VS Code. Consulte GitHub issue #1865
  • Algumas operações podem exigir permissões elevadas dependendo do aplicativo de destino
  • Apenas Windows é suportado
  • O MCPControl funciona melhor na resolução 1280x720, tela única. A precisão de cliques é otimizada para esta resolução. Estamos trabalhando em um bug de deslocamento/escala e procurando testadores ou ajuda para criar ferramentas de teste

👥 Contribuindo

Consulte CONTRIBUTING.md

⚖️ Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

📖 Referências

MseeP.ai Security Assessment Badge