Windows Control

Control programático sobre operaciones del sistema Windows, incluyendo mouse, teclado, gestión de ventanas y captura de pantalla utilizando nut.js.

GitHub
332
Prueba este MCPPatrocinado

Documentación

MCPControl

MCPControl Logo

Latest Release

Servidor de control de Windows para el Model Context Protocol, que proporciona control programático de operaciones del sistema, incluyendo mouse, teclado, gestión de ventanas y funcionalidad de captura de pantalla.

Nota: Este proyecto actualmente solo es compatible con Windows.

🔥 ¿Por qué MCPControl?

MCPControl cierra la brecha entre los modelos de IA y tu escritorio, permitiendo un control seguro y programático de:

  • 🖱️ Movimientos y clics del mouse
  • ⌨️ Entrada de teclado y atajos
  • 🪟 Gestión de ventanas
  • 📸 Captura y análisis de pantalla
  • 📋 Operaciones de portapapeles

🔌 Inicio Rápido

Requisitos Previos

  1. Instalar Build Tools (incluyendo la carga de trabajo de 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. Instalar Python (si aún no está instalado)

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

  3. Instalar Node.js

    # Install latest LTS version
winget install OpenJS.NodeJS

Instalación

  1. Instalar el Paquete MCPControl 
    npm install -g mcp-control

Configuración

MCPControl funciona mejor en una máquina virtual a resolución 1280x720 para una precisión óptima de clics.

Configura tu cliente de Claude para conectarse a MCPControl mediante transporte SSE:

Opción 1: Conexión SSE Directa

Para conectarte a un servidor MCPControl que se ejecuta en una VM o máquina remota:

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

Reemplaza 192.168.1.100:3232 con la dirección IP y el puerto de tu servidor.

Opción 2: Inicio Local con SSE

Para iniciar MCPControl localmente con transporte SSE:

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

Iniciando el Servidor

Primero, inicia el servidor MCPControl en tu VM o máquina local:

mcp-control --sse

El servidor mostrará:

  • Las interfaces de red disponibles y sus direcciones IP
  • El número de puerto (predeterminado: 3232)
  • Mensajes de estado de conexión

Ejemplo de Configuración de VM

  1. Inicia tu VM de Windows con resolución 1280x720
  2. Instala MCPControl en la VM: 
    npm install -g mcp-control
  3. Ejecuta el servidor con transporte SSE: 
    mcp-control --sse
  4. Anota la dirección IP de la VM (por ejemplo, 192.168.1.100)
  5. Configura Claude con la URL SSE: 
    {
  "mcpServers": {
    "MCPControl": {
      "transport": "sse",
      "url": "http://192.168.1.100:3232/mcp"
    }
  }
}
  6. Reinicia Claude y ¡MCPControl aparecerá en tu menú de MCP!

🔧 Opciones de CLI

MCPControl admite varias banderas de línea de comandos para configuraciones avanzadas:

# 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 Línea de Comandos

  • --sse - Habilita el transporte SSE (Server-Sent Events) para acceso de red
  • --port [number] - Especifica un puerto personalizado (predeterminado: 3232)
  • --https - Habilita HTTPS/TLS (requerido para implementaciones remotas según la especificación MCP)
  • --cert [path] - Ruta al archivo de certificado TLS (requerido con --https)
  • --key [path] - Ruta al archivo de clave privada TLS (requerido con --https)

Nota de Seguridad

Según la especificación MCP, HTTPS es obligatorio para todos los transportes basados en HTTP en entornos de producción. Al implementar MCPControl para acceso remoto, usa siempre la bandera --https con certificados TLS válidos.

🚀 Casos de Uso Populares

Automatización Asistida

  • Pruebas de Aplicaciones: Delega pruebas de UI repetitivas a Claude, permitiendo que la IA navegue por las aplicaciones y reporte problemas
  • Automatización de Flujos de Trabajo: Haz que Claude opere aplicaciones en tu nombre, manejando tareas repetitivas mientras tú te enfocas en trabajo creativo
  • Relleno de Formularios: Deja que Claude maneje tareas de entrada de datos con tu supervisión

Experimentación con IA

  • IA en Juegos: Observa a Claude aprender a jugar juegos simples mediante retroalimentación visual
  • Razonamiento Visual: Prueba la capacidad de Claude para navegar interfaces visuales y resolver acertijos visuales
  • Colaboración Humano-IA: Explora nuevos paradigmas de interacción donde Claude puede ver tu pantalla y ayudar con tareas complejas

Desarrollo y Pruebas

  • Integración Entre Aplicaciones: Conecta aplicaciones que normalmente no se comunican
  • Marco de Pruebas de UI: Crea escenarios de prueba robustos con validación visual
  • Creación de Demos: Automatiza la creación de demostraciones de productos

⚠️ AVISO IMPORTANTE

ESTE SOFTWARE ES EXPERIMENTAL Y POTENCIALMENTE PELIGROSO

Al usar este software, reconoces y aceptas que:

  • Dar a los modelos de IA control directo sobre tu computadora a través de esta herramienta es inherentemente riesgoso
  • Este software puede controlar tu mouse, teclado y otras funciones del sistema, lo que podría causar consecuencias no intencionadas
  • Estás usando este software completamente bajo tu propio riesgo
  • Los creadores y colaboradores de este proyecto NO aceptan responsabilidad alguna por daños, pérdida de datos u otras consecuencias que puedan surgir del uso de este software
  • Esta herramienta solo debe usarse en entornos controlados con las medidas de seguridad adecuadas

ÚSALO BAJO TU PROPIO RIESGO

🌟 Características

🪟 Gestión de Ventanas

  • Listar todas las ventanas
  • Obtener información de la ventana activa
  • Enfocar, redimensionar y reposicionar

🖱️ Control del Mouse

  • Movimiento de precisión
  • Operaciones de clic y arrastre
  • Desplazamiento y seguimiento de posición

⌨️ Control del Teclado

  • Entrada de texto y combinaciones de teclas
  • Control de presión/liberación de teclas
  • Funcionalidad de mantener tecla presionada

📸 Operaciones de Pantalla

  • Capturas de pantalla de alta calidad
  • Detección del tamaño de pantalla
  • Captura de ventana activa

🔧 Proveedores de Automatización

MCPControl admite múltiples proveedores de automatización para diferentes casos de uso:

  • keysender (predeterminado) - Automatización nativa de Windows con alta fiabilidad
  • powershell - Automatización basada en Windows PowerShell para operaciones más simples
  • autohotkey - Scripting con AutoHotkey v2 para necesidades de automatización avanzadas

Configuración del Proveedor

Puedes configurar el proveedor de automatización usando variables de entorno:

# 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"

O usa configuración modular para operaciones 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

Consulta la documentación específica del proveedor:

🛠️ Configuración de Desarrollo

Si estás interesado en contribuir o compilar desde el código fuente, consulta CONTRIBUTING.md para instrucciones detalladas.

Requisitos de Desarrollo

Para compilar este proyecto para desarrollo, necesitarás:

  1. Sistema operativo Windows (requerido para la dependencia keysender)
  2. Node.js 18 o posterior (instálalo usando el instalador oficial de Windows que incluye herramientas de compilación)
  3. Administrador de paquetes npm
  4. Herramientas de compilación nativas:
    • node-gyp: npm install -g node-gyp
    • cmake-js: npm install -g cmake-js

La dependencia keysender se basa en módulos nativos específicos de Windows que requieren estas herramientas de compilación.

📋 Estructura del Proyecto

  • /src
    • /handlers - Manejadores de solicitudes y gestión de herramientas
    • /tools - Implementaciones de funcionalidad principal
    • /types - Definiciones de tipos de TypeScript
    • index.ts - Punto de entrada principal de la aplicación

🔖 Ramas del Repositorio

  • main - Rama principal de desarrollo con las últimas características y cambios
  • release - Rama de lanzamiento estable que refleja la última etiqueta estable (actualmente v0.2.0)

Instalación de Versiones

Puedes instalar versiones específicas de 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

📚 Dependencias

🚧 Limitaciones Conocidas

  • Las operaciones de minimizar/restaurar ventanas no son compatibles actualmente
  • Las funciones de múltiples pantallas pueden no funcionar como se espera, dependiendo de la configuración
  • La utilidad get_screenshot no funciona con la Extensión Cline de VS Code. Consulta GitHub issue #1865
  • Algunas operaciones pueden requerir permisos elevados dependiendo de la aplicación objetivo
  • Solo se admite Windows
  • MCPControl funciona mejor a resolución 1280x720, pantalla única. La precisión de clics está optimizada para esta resolución. Estamos trabajando en un error de desplazamiento/escalado y buscamos evaluadores o ayuda para crear herramientas de prueba

👥 Contribuciones

Consulta CONTRIBUTING.md

⚖️ Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

📖 Referencias

MseeP.ai Security Assessment Badge