mcp-screenshot

Русская версия ниже / Russian version below

A small Model Context Protocol (MCP) server that gives an LLM eyes on your desktop without burning context. It can take one-off screenshots, crop a region around the mouse cursor, and run timed streaming sessions that save frames to disk and only return image bytes when explicitly asked.

Why this exists

Most LLM workflows that need to "look at the screen" either:

1. Drop a full-resolution PNG into the model context every call — which eats tokens fast and slows the conversation.
2. Run a separate vision pipeline that the model can't directly query.

This server takes a middle road. Captures are persisted to disk; the MCP tools return small metadata blobs (filePath, bytes, dimensions, cursor info) plus the image only when you ask for includeBase64=true or call stream_latest. Streaming sessions keep a bounded ring of recent frames in memory so a 5-minute capture session at 1 fps doesn't blow memory either.

It also exposes the mouse cursor position and the title of the window under the cursor, so the model can ground its analysis ("you are looking at the window titled X at the top-right of the screen") without guessing.

Tools

Tool	What it does
screenshot	One-shot capture. Optional cursor-region crop, format, quality, resize.
cursor_info	Cursor coords + foreground window + window directly under the cursor.
stream_start	Start a timed periodic capture (interval + duration).
stream_status	Snapshot of a session: frame count, time remaining, recent frames.
stream_latest	Read the most recent frame from disk and return it as base64.
stream_stop	Stop a running session early. Frames already on disk are kept.
stream_list	List all known sessions.
stream_drop	Forget a finished session (frees its in-memory ring).

Defaults are tuned for legibility on 4K monitors:

• Single screenshots — JPEG, quality 82, longest edge 2400px.
• Streams — JPEG, quality 72, longest edge 1920px.
• When cursorRadius>0 the cursor crop is kept at native resolution (no resize) unless you override maxEdge explicitly.

Pass maxEdge: 0 to disable resizing entirely; pass any positive value to override.

Install

git clone https://github.com/beekamai/mcp-screenshot.git
cd mcp-screenshot
npm install
npm run build

Wire it into any MCP-capable client by pointing it at node dist/index.js over stdio. Most CLI-based clients have an mcp add subcommand:

your-mcp-client mcp add screenshot --scope user -- node /absolute/path/to/mcp-screenshot/dist/index.js

Platform notes

• Windows: uses System.Drawing via PowerShell. No native binaries shipped. Cursor probe and screen capture both work without admin rights. Multi-monitor selection is supported via the display argument (0 = first monitor, omit = full virtual screen).
• macOS / Linux: capture falls back to screenshot-desktop if installed. The cursor probe currently only reports x = -1, y = -1 outside of Windows; contributions welcome.

Privacy

Everything is local. The server runs as a stdio process, captures are saved under ./captures/ next to the package by default, and nothing is sent over the network unless your MCP client transports the bytes. Delete the captures/ directory when you're done.

License

MIT.

---

<a id="mcp-screenshot-ru"></a>

mcp-screenshot (RU)

Небольшой MCP-сервер, который даёт языковой модели возможность видеть рабочий стол, не съедая контекст. Он умеет делать одиночные скриншоты, вырезать область вокруг курсора и запускать сессии покадрового стриминга, которые пишут кадры на диск и возвращают пиксели только тогда, когда модель явно их запросила.

Зачем это нужно

Стандартные подходы к "смотри на экран":

1. Передавать модели каждый раз PNG в полный размер — токены кончаются быстро, и диалог становится тормозным.
2. Использовать отдельный vision-конвейер, к которому модель не имеет прямого доступа.

Этот сервер идёт средним путём: каждый снимок сохраняется на диск, а MCP-тулы возвращают компактный JSON (filePath, размер файла, разрешение, информация о курсоре). Изображение приходит в ответе только если в screenshot передан includeBase64=true или если позже вызван stream_latest. У стримов есть ограниченное кольцо последних кадров в памяти, так что пятиминутная сессия с частотой 1 fps не разнесёт RAM.

Дополнительно сервер сообщает координаты курсора и заголовок окна под ним — модель может опираться на это, не угадывая ("ты сейчас смотришь на окно X в правом верхнем углу").

Тулы

Тул	Что делает
screenshot	Одиночный снимок. Опционально — обрезка вокруг курсора, формат, качество.
cursor_info	Координаты курсора, активное окно и окно под курсором.
stream_start	Запуск таймера с периодической съёмкой (интервал + длительность).
stream_status	Снимок состояния сессии: число кадров, остаток времени, последние кадры.
stream_latest	Прочитать последний кадр с диска и вернуть base64.
stream_stop	Прервать сессию досрочно. Кадры на диске сохраняются.
stream_list	Список всех сессий.
stream_drop	Забыть завершённую сессию (освобождает кольцо в памяти, файлы остаются).

Дефолты подобраны под 4K-мониторы — текст на интерфейсах остаётся читаемым:

• Одиночные снимки — JPEG, качество 82, длинная сторона 2400px.
• Стримы — JPEG, качество 72, длинная сторона 1920px.
• При cursorRadius>0 обрезка вокруг курсора сохраняется в нативном разрешении (без ресайза), если явно не задан maxEdge.

maxEdge: 0 полностью отключает уменьшение, любое положительное значение — переопределяет дефолт.

Установка

git clone https://github.com/beekamai/mcp-screenshot.git
cd mcp-screenshot
npm install
npm run build

Подключение к любому MCP-клиенту — указать запуск node dist/index.js через stdio. У большинства CLI-клиентов есть подкоманда mcp add:

your-mcp-client mcp add screenshot --scope user -- node /абсолютный/путь/к/mcp-screenshot/dist/index.js

Платформы

• Windows: захват через System.Drawing (вызов из PowerShell), без бандленных нативных бинарей. Курсорный пробник и скриншоты работают без прав администратора. Мульти-мониторный выбор — параметр display (0 — первый монитор, без аргумента — весь виртуальный экран).
• macOS / Linux: захват — fallback на screenshot-desktop. Курсорный пробник сейчас возвращает x = -1, y = -1 вне Windows; PR приветствуются.

Приватность

Всё локально. Сервер крутится как stdio-процесс, кадры лежат в ./captures/ рядом с пакетом, ничего не уходит в сеть, пока ваш MCP-клиент сам не передаст байты дальше. После работы — просто удалите каталог captures/.

Лицензия

MIT.