MCPControl

Controlar programaticamente o mouse, teclado, gerenciamento de janelas, captura de tela e operações de área de transferência do Windows.

GitHub
331
Experimente este MCPPatrocinado

Documentação

MCPControl

MCPControl Logo

Latest Release

Servidor de controle para Windows do 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ários sinalizadores 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 à 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 o sinalizador --https com certificados TLS válidos.

🚀 Casos de Uso Populares

Automação Assistida

  • Teste de Aplicativos: Delegue testes de UI repetitivos 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 Teste 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 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 da tela
  • Captura da 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 (necessá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 mudanças mais recentes
  • release - Branch de lançamento 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
  • Múltiplas funções de tela 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 alvo
  • Apenas Windows é suportado
  • O MCPControl funciona melhor em resolução 1280x720, tela única. A precisão dos 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