Laz.Mcp 0.2.0

Laz.Mcp

An MCP (Model Context Protocol) server that exposes the Laz library's mouse, keyboard, and screen-capture automation as tools an LLM client can call.

Laz simulates real OS-level input (mouse, keyboard) and reads real pixels off the screen on Windows, Linux (X11/XWayland), and macOS. This server just wraps that library's public API 1:1 (plus a couple of small ergonomic conveniences) as MCP tools — it does not add new automation capabilities beyond what Laz already does.

This grants a connected LLM control of your actual mouse and keyboard. Only run it in a session/user context you're comfortable handing that control to, and prefer running it in a disposable VM or sandboxed desktop session for anything you don't fully trust.

Why this one

There are several other MCP servers for desktop automation (RobotJS-, PyAutoGUI-, AutoHotkey-, or native-backed). Most converge on the same base — click/move/drag, keypress/type, screenshot — with window management, clipboard access, or OCR bolted on as extras, and most that claim "cross-platform" are really Windows- or macOS-first with the other platforms added on top.

Laz.Mcp stays narrow on purpose and differs on two things:

• Natural mouse movement. mouse_move_smooth and mouse_drag_and_drop travel a linear or bezier path under a choice of 9 easing curves, rather than a flat duration parameter or an instant jump. Relevant if the target app (or a bot-detection layer) treats motion trajectory as a signal.
• One implementation across Windows, Linux (X11/XWayland), and macOS, from Laz's native input handling on each platform, rather than a single-OS core with other platforms shimmed in.

It doesn't do window management, clipboard access, or OCR — this stays a thin, reliable primitives layer over mouse, keyboard, and screen, meant to be a building block for whatever agent logic you put on top of it, not a full computer-use framework.

Transport

Stdio only. The server is a console app launched by an MCP client (Claude Desktop, Claude Code, etc.) over stdin/stdout — no network listener.

Coordinates

All positions are integer (x, y) screen pixels in Laz's coordinate space (see platform notes in the Laz README — DPI-awareness matters on Windows, and Wayland/XWayland HiDPI setups can behave unexpectedly on Linux). Call screen_get_size or screen_list_displays first to get valid bounds instead of guessing coordinates/regions.

Tools

Mouse

mouse_move_smooth and mouse_drag_and_drop are synchronous and block for the full durationMs (default 1.5s) while they play out the motion — that's inherent to Laz's move implementation, not an artifact of the server.

Keyboard

key accepts the case-insensitive name of a Laz.Key enum member, e.g. A-Z, Zero-Nine, F1-F24, Enter, Tab, Esc, Space, Backspace, Delete, Insert, Left/Right/Up/Down, Home, End, PageUp, PageDown, Shift, Control, Alt, LeftShift/RightShift/ LeftControl/RightControl/LeftAlt/RightAlt, LeftWin/RightWin, CapsLock, NumLock, ScrollLock, Numpad0-Numpad9 and NumpadPlus/NumpadMinus/NumpadMultiply/NumpadDivide/ NumpadDecimal/NumpadEquals/NumpadSeparator, punctuation (Semicolon, Equal, Comma, Minus, Dot, Slash, Grave, OpenBracket, Backslash, CloseBracket, Apostrophe), and media/browser/volume keys. An invalid name returns a tool error listing this guidance rather than throwing a raw exception.

Screen

macOS requires the Screen Recording permission to be granted to the host process for both screen_capture and screen_get_color_at; the OS prompts on first use. macOS and Linux also require Accessibility / an active X11-or-XWayland session respectively for mouse and keyboard tools — see the Laz README's per-platform remarks for each method.

screen_get_size/screen_list_displays are implemented outside of Laz (which has no such API — see Implementation notes below) via direct OS calls, so they have their own platform caveats: Linux requires xrandr on an X11/XWayland session (no Wayland-native support) and always reports scaleFactor: 1.0 since xrandr --query doesn't expose per-monitor DPI. Windows' scaleFactor reflects real per-monitor DPI only once the process is DPI-aware; an unaware process reports 1.0 for every monitor.

Configuration

• LAZ_DELAY_MS env var — overrides Laz's default 50ms inter-event delay (used between chained actions like keyboard_stroke and between characters in keyboard_type). Set before the server process starts.

Implementation notes (for the build)

• .NET 10, ModelContextProtocol + Microsoft.Extensions.Hosting for the stdio server host.
• A single Laz.Lazbot instance is held for the process lifetime and all calls into it are serialized behind one lock, since it manipulates global OS input/cursor state and two tool calls interleaving mid-gesture (e.g. a click landing in the middle of a drag) would be a real bug, not just a theoretical race.
• screen_capture's raw BGRA bytes are encoded to PNG (via SixLabors.ImageSharp, for cross-platform support — System.Drawing is Windows-only) before being returned as an ImageContentBlock.
• Enum-like parameters (key, button, path, easing) are accepted as strings and parsed with Enum.TryParse(ignoreCase: true), throwing McpException with a specific message on failure, rather than relying on the default JSON-schema enum-as-integer serialization — this keeps error messages legible to the model instead of a generic "invocation failed".
• screen_get_size/screen_list_displays are the one deliberate exception to "thin wrapper over Laz": since Laz exposes no screen-size or monitor-enumeration API, ScreenInterop.cs goes straight to the OS instead — Win32 (EnumDisplayMonitors/GetMonitorInfo/Shcore.dll!GetDpiForMonitor) on Windows, CoreGraphics (CGGetActiveDisplayList/CGDisplayBounds/CGDisplayCopyDisplayMode) on macOS, and an xrandr --query shell-out on Linux. It deliberately never touches process DPI awareness (e.g. SetProcessDpiAwarenessContext) since Laz's own native code already establishes whatever awareness context its mouse coordinate mapping relies on, and overriding that independently could silently break mouse_jump_to/mouse_move_smooth accuracy.