desktop-control-mcp

Un servidor de automatización de escritorio para Windows que expone control de ratón, teclado, captura de pantalla y detección de elementos de interfaz impulsada por IA a través de dos interfaces:

• Servidor MCP (mcp_server.py): transporte stdio, diseñado para usarse con Claude Code, Claude Desktop y otros clientes MCP.

• Servidor HTTP (server.py + app.py): una API Flask en http://localhost:7845, ejecutable desde un icono de la bandeja del sistema.

Ambas interfaces comparten el mismo controller.py subyacente (automatización de Windows) y ui_parser.py (modelos de visión), por lo que las capacidades son idénticas.

Características destacadas

• Clic basado en visión IA: los elementos de la interfaz se detectan con Microsoft OmniParser v2 (detector de iconos YOLO + descripción de Florence-2 + EasyOCR), lo que permite apuntar a botones/campos por intención en lugar de adivinar coordenadas de píxeles a partir de una captura de pantalla.

• Consciente de DPI: se ejecuta como PROCESS_PER_MONITOR_DPI_AWARE, por lo que las coordenadas siempre están en píxeles físicos independientemente de la escala de visualización de Windows.

• Cursor en las capturas: el mapa de bits real del cursor de Windows se compone en cada captura a través de la API GDI de Win32, para que los clientes de IA puedan ver dónde está el ratón.

• Tres modos de captura: JPEG comprimido único, vista anotada de detección y captura de ráfaga distribuida en el tiempo (para observar animaciones o estados de carga).

• Dispatch de teclado inteligente: herramientas separadas para texto literal, teclas individuales y combinaciones con modificadores, de modo que "ctrl+c" nunca se escriba por error como texto.

Related MCP server: desktop-automation-mcp

Instalación

Requiere Windows y Python 3.10+.

git clone https://github.com/ahmetdenizyilmaz/desktop-control-mcp.git
cd desktop-control-mcp
pip install -r requirements.txt

En la primera ejecución, los pesos del modelo OmniParser v2 (~1 GB) se descargan de Hugging Face a la caché local. La GPU se usa automáticamente si PyTorch con CUDA está instalado; de lo contrario, se usa la CPU.

Ejecución

Como servidor MCP (stdio)

Añade una entrada como esta a la configuración de tu cliente MCP (p. ej., Claude Desktop / Claude Code):

{
  "mcpServers": {
    "desktop-control": {
      "command": "python",
      "args": ["C:\\path\\to\\desktop-control-mcp\\mcp_server.py"]
    }
  }
}

El servidor arranca inmediatamente; los modelos se cargan en un hilo en segundo plano, de modo que la primera llamada a detect_ui_elements espera por ellos, pero el resto de herramientas están disponibles de inmediato.

Como servidor HTTP con icono de bandeja

python app.py

Aparece un icono de bandeja con opciones Iniciar, Detener y Salir. La API Flask escucha en http://localhost:7845. Consulta API_DOCS.md para los detalles de los endpoints.

Herramientas MCP

Pantalla

Capturas de pantalla

Ratón

Teclado

El ciclo de clic obligatorio

Las coordenadas no son estables entre cambios de pantalla: cada menú que se abre, cada diálogo, cada cambio de estado invalida las coordenadas de una captura anterior. El servidor impone este ciclo:

1. DETECTAR — detect_ui_elements devuelve una captura anotada más una tabla de todos los elementos detectados (tipo, confianza, centro, etiqueta).

2. ENCONTRAR — identifica el elemento objetivo en la tabla.

3. HACER CLIC — click_mouse(x, y) con las coordenadas exactas del centro de la tabla.

4. VERIFICAR — take_screenshot para confirmar que el clic tuvo efecto.

5. REINTENTAR — si el clic falló, re-detectar y volver a intentar.

Nunca calcules coordenadas a partir de una captura de pantalla en bruto. La tabla de elementos de detect_ui_elements es la fuente de verdad.

Ejemplo de tabla de elementos

  ID  Type   Conf   Center         Label
   1  text   0.98   ( 499,   55)   File  Edit  View
   2  icon   0.91   ( 674,  200)   Search button
   3  icon   0.87   (1200,  400)   Close

Para hacer clic en el botón de búsqueda: click_mouse(x=674, y=200).

API HTTP

Cuando se ejecuta como app.py, el servidor Flask en el puerto 7845 replica las herramientas MCP:

Los esquemas completos de solicitud/respuesta están en API_DOCS.md.

Estructura de archivos

mcp_server.py          FastMCP server — tool definitions and lifespan
controller.py          Win32 / pyautogui / mss core — screenshots, input, window info
ui_parser.py           OmniParser v2 loading + UI detection + image annotation
screenshot_manager.py  Disk-side screenshot cache (cleanup, naming, burst dirs)
overlay.py             On-screen overlay utilities
lock_manager.py        Concurrency lock for shared resources
server.py              Flask HTTP API
app.py                 Tray-icon launcher for the Flask server
templates/index.html   Web UI for the Flask server
requirements.txt       Python dependencies
API_DOCS.md            HTTP endpoint reference
run_agents.bat         Convenience launcher for Claude Code in this folder

Notas de plataforma

• Solo Windows. La composición del cursor, el reconocimiento de DPI y el código de ventana activa usan directamente APIs Win32.

• Solo monitor principal. Todas las coordenadas están en el espacio de píxeles del monitor principal.

• La primera detección es lenta. La carga del modelo OmniParser y la inicialización de EasyOCR pueden tardar 30–60 segundos en la primera llamada. Las siguientes detecciones son rápidas (unos segundos en GPU, unos pocos más en CPU).