screen-mcp

MCP-сервер (Model Context Protocol), который даёт AI-агентам глаза на Wayland-рабочем столе Omarchy / Hyprland. Он делает скриншоты через grim и предлагает опциональный анализ изображений на основе Gemini API — полезно, когда у вызывающей модели нет встроенного визуального энкодера.

Возможности

Скриншоты используют grim (протокол wlroots screencopy) — X11 не требуется.

Предварительные требования

• Omarchy, Hyprland или любой Wayland-композитор на основе wlroots

• grim — инструмент создания скриншотов Wayland

• slurp — (необязательно) интерактивный помощник выбора области

• hyprctl — CLI для окон/запросов Hyprland

• jq — (необязательно) используется некоторыми вспомогательными скриптами

Проверьте с помощью:

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

Для анализа изображений (необязательно)

• Ключ Gemini API — получите его на https://aistudio.google.com

• Экспортируйте его в своём окружении:

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

Без ключа инструменты создания скриншотов продолжат работать; только analyze_image и screenshot_and_analyze будут возвращать ошибку.

Установка

Через Claude Desktop

Добавьте это в claude_desktop_config.json в Claude Desktop:

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

Через npx

npx -y screen-mcp

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

Примеры использования

Захват области экрана

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

Захват конкретного окна

Сначала выведите список доступных окон, чтобы получить адрес или заголовок:

list_windows()

Затем захватите окно по заголовку (частичное совпадение), адресу или "focused":

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

Анализ изображения с помощью Gemini

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

Или передайте данные изображения в base64 напрямую:

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

Захват и анализ одним вызовом

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

Разработка

# Install deps
npm install

# Build
npm run build

# Run
npm start

# Development (recompile on change)
npm run dev

Как это работает

• Захват: src/capture.ts оборачивает grim (скриншоты) и hyprctl (перечисление окон). Захват окна сначала пробует grim -T <stableId> (дескриптор foreign-toplevel), а при неудаче использует grim -g "<x>,<y> <w>x<h>" (геометрия из hyprctl).

• Анализ: src/gemini.ts использует официальный SDK @google/genai. Изображения передаются встроенно в формате base64 в конечную точку interactions.create Gemini API.

• Сервер: src/index.ts связывает всё вместе как MCP-сервер с stdio-транспортом, используя @modelcontextprotocol/server.

Лицензия

MIT