screen-mcp

Un servidor MCP (Model Context Protocol) que les da a los agentes de IA ojos en un escritorio Wayland Omarchy / Hyprland. Captura capturas de pantalla mediante grim y ofrece análisis de imágenes opcional impulsado por la API de Gemini, útil cuando el modelo que realiza la llamada no tiene codificador de visión nativo.

Características

Las capturas de pantalla usan grim (protocolo screencopy de wlroots); no se requiere X11.

Requisitos previos

• Omarchy, Hyprland o cualquier compositor Wayland basado en wlroots

• grim — herramienta de captura de pantalla para Wayland

• slurp — (opcional) ayudante interactivo para selección de regiones

• hyprctl — CLI de ventanas/consultas de Hyprland

• jq — (opcional) usado por algunos scripts auxiliares

Verifica con:

grim --help && hyprctl clients -j | head -c 20

Para el análisis de imágenes (opcional)

• Una clave de API de Gemini: consíguela en https://aistudio.google.com

• Expórtala en tu entorno:

export GEMINI_API_KEY="your-api-key-here"

Sin la clave, las herramientas de captura siguen funcionando; solo analyze_image y screenshot_and_analyze devolverán un error.

Instalación

Mediante Claude Desktop

Añade esto a tu claude_desktop_config.json de Claude Desktop:

{
  "mcpServers": {
    "screen-mcp": {
      "command": "npx",
      "args": ["-y", "screen-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Mediante npx

npx -y screen-mcp

# Or install globally:
npm install -g screen-mcp

Ejemplos de uso

Capturar una región de la pantalla

screenshot_region(x=100, y=200, width=800, height=600, include_cursor=true)

Capturar una ventana específica

Primero enumera las ventanas disponibles para obtener una dirección o un título:

list_windows()

Luego captura por título (coincidencia de subcadena), dirección o "focused":

screenshot_window(window="Spotify")
screenshot_window(window="focused")
screenshot_window(window="0x557ba79b4900")

Analizar una imagen con Gemini

analyze_image(
  image_path="/tmp/my-screenshot.png",
  prompt="What applications are visible in this screenshot?",
  model="gemini-2.5-flash"
)

O pasa directamente datos de imagen codificados en base64:

analyze_image(
  image="<base64-encoded-image>",
  prompt="Describe what you see in this image.",
  mime_type="image/png"
)

Capturar y analizar en una sola llamada

screenshot_and_analyze(
  x=0, y=0, width=1920, height=1080,
  prompt="Count the number of windows open and list their titles.",
  scale=0.5,
  model="gemini-2.5-flash"
)

Desarrollo

# Install deps
npm install

# Build
npm run build

# Run
npm start

# Development (recompile on change)
npm run dev

Cómo funciona

• Captura: src/capture.ts envuelve grim (capturas de pantalla) y hyprctl (enumeración de ventanas). La captura de ventanas primero intenta grim -T <stableId> (manejador foreign-toplevel) y, si falla, recurre a grim -g "<x>,<y> <w>x<h>" (geometría de hyprctl).

• Análisis: src/gemini.ts utiliza el SDK oficial @google/genai. Las imágenes se pasan en línea como base64 al endpoint interactions.create de la API de Gemini.

• Servidor: src/index.ts conecta todo como un servidor MCP con transporte stdio usando @modelcontextprotocol/server.

Licencia

MIT