desktop-mcp

Visión y control de escritorio para LLMs en Linux, incluido Wayland — el modelo toma una captura de pantalla de toda la pantalla y hace clic, escribe y desplaza sobre lo que ve. MCP simple sobre stdio, por lo que funciona en Claude Code, Claude Desktop, Cursor o cualquier otro cliente MCP.

Léelo primero: puede que no lo necesites

Anthropic incluye el uso de computadora de forma nativa, y donde eso funcione deberías usarlo en su lugar: está mejor integrado y realmente se mantiene:

• macOS y Windows: Claude Desktop tiene el uso de computadora integrado, en Cowork y Claude Code. Controla tu escritorio real. (docs)

• Construyendo tu propio agente: la API de Claude tiene una herramienta computer de primera parte (GA como el conjunto de herramientas computer_toolset_20260801). (docs)

El vacío que esto llena es Linux. A partir de agosto de 2026, el uso de computadora no está disponible en la aplicación de escritorio de Linux, y la automatización de escritorio en Wayland es genuinamente incómoda de una manera que X11 nunca lo fue:

• El compositor de COSMIC no implementa wlr-screencopy, por lo que grim falla por completo y cada herramienta de captura de pantalla necesita una ruta por compositor.

• No hay protocolo para consultar la posición del cursor, ni para enumerar las ventanas de otro cliente.

• La entrada debe ir por debajo del compositor a través de /dev/uinput, porque el ydotool comúnmente empaquetado expone un puntero relativo cuyos saltos largos se estropean con la aceleración del puntero.

Si estás en macOS o Windows, este repositorio es en su mayoría redundante. Si estás en Linux — particularmente Wayland — es la opción que funciona.

Los servidores MCP de automatización de escritorio no son una categoría nueva; hay miles de servidores MCP. Lo específico aquí es la ruta de entrada absoluta-uinput nativa de Wayland, medida con precisión de píxel en COSMIC.

Related MCP server: mcp-linux-desktop

Estado

Escrito para ser multiplataforma, pero solo una configuración se ha ejercitado realmente. El resto son rutas de código, no evidencia: trátalo en consecuencia.

Qué se probó y cómo

Verificado de extremo a extremo en:

• Pop!_OS 24.04 LTS, kernel 7.0.11, COSMIC (cosmic-comp 1.0.0), Wayland, pantalla única 2560x1440, Python 3.13.

Resultados:

No probado y vale la pena saberlo: diseños de múltiples monitores, escalado HiDPI, diseños de teclado no estadounidenses en la ruta de códigos de tecla crudos (wtype los maneja correctamente; los códigos de tecla uinput asumen US), y cada compositor que no sea COSMIC.

Se agradecen informes de otras plataformas: desktop_info vuelca todo lo necesario para diagnosticar un problema de backend.

Instalación

git clone <this repo> && cd desktop-mcp
uv venv && uv pip install -e .

macOS, Windows y Linux/X11 también necesitan las dependencias de entrada:

uv pip install -e ".[gui]"

Linux: configuración de permisos única

Inyectar entrada en Wayland significa escribir en /dev/uinput, que es propiedad de root por defecto:

bash scripts/setup-linux.sh   # needs sudo once
# then log out and back in

macOS: configuración de permisos única

Concede Grabación de pantalla y Accesibilidad a la aplicación que inicie el servidor (Terminal, iTerm, Claude Desktop) en Configuración del sistema → Privacidad y seguridad.

Conéctalos

Claude Code:

claude mcp add desktop -- /absolute/path/to/desktop-mcp/.venv/bin/python -m desktop_mcp.server

Claude Desktop (claude_desktop_config.json) y Cursor (.cursor/mcp.json) usan la misma forma:

{
  "mcpServers": {
    "desktop": {
      "command": "/absolute/path/to/desktop-mcp/.venv/bin/python",
      "args": ["-m", "desktop_mcp.server"]
    }
  }
}

Herramientas

Coordenadas

Las capturas de pantalla se reducen (borde largo de 1400px por defecto) antes de enviarse, por lo que el modelo trabaja en píxeles de imagen; el servidor los mapea de vuelta a píxeles de pantalla en cada llamada. Pasa exactamente las coordenadas que lees de la captura.

Este es el detalle que la mayoría de las herramientas caseras de uso de computadora fallan. Si lo omites, cada clic aterriza en una fracción consistente de donde se apuntaba.

Por qué /dev/uinput en lugar de ydotool en Linux

Las compilaciones de ydotool comúnmente empaquetadas exponen un puntero relativo, por lo que un salto a (1280, 720) se entrega como un gran movimiento relativo, que el compositor pasa por la aceleración del puntero. El cursor aterriza cerca del objetivo en lugar de sobre él, y el error crece con la distancia. Un dispositivo uinput absoluto evita la aceleración: medido 5/5 exacto en una pantalla de 2560x1440. ydotool sigue siendo un respaldo cuando /dev/uinput no es escribible.

Tiempo de clic

Los compositores despachan el movimiento del puntero de forma asíncrona, y los toolkits ignoran una pulsación de botón que llega antes de que hayan procesado el movimiento que puso el cursor sobre el widget. Medido en COSMIC: un intervalo de 30ms entre mover y pulsar resalta de manera confiable un botón pero nunca lo activa: el estado de hover es prueba de que las coordenadas son correctas, lo que hace que este fallo sea fácil de malinterpretar como un error de apuntado. 250ms lo activa. Una pulsación también debe mantenerse (~90ms) para registrarse como un clic real en lugar de un evento suelto.

Ambos retrasos son ajustables; bájalos solo si tu escritorio lo tolera.

Seguridad

Esto le da a un modelo el mismo alcance sobre la máquina que la persona sentada frente a ella. Puede leer cualquier cosa en pantalla — administradores de contraseñas abiertos, mensajes privados, tokens — y hacer clic en cualquier cosa, incluidos botones destructivos. Trata una sesión como si le hubieras entregado tu teclado a alguien.

Variables de entorno:

ctrl+alt+F1–F12 siempre están bloqueados; el cambio de VT puede sacar la sesión gráfica de debajo de ti.

Una configuración de revisor de solo lectura:

DESKTOP_MCP_READ_ONLY=1 python -m desktop_mcp.server

Verificar

.venv/bin/python scripts/mcp_smoke.py   # real stdio MCP round trip