MCP server for Linux desktop GUI automation on KDE Plasma 6 Wayland — virtual testing and live desktop automation
kwin-mcp demonstrates strong definition quality with 30 well-named, action-verb-prefixed tools covering a cohesive desktop automation domain. Nearly all tools have descriptions (28/30 fully described, 2 minimal). Input schemas are consistently present with proper types and descriptions. However, output schemas are not explicitly documented in the visible code, and error handling guidance is minimal. The server follows most tool patterns but lacks some production-grade error classification and recovery guidance expected at 80+.
Get the accessibility tree of apps in the isolated session. Returns a formatted text tree with each widget's role, name, states, and bounding box coordinates. Use this to understand UI structure before interacting with elements.
Clear the last error message.
Get the current clipboard contents.
Set the clipboard contents.
Drag from current mouse position to target coordinates.
Click on a UI element found by query.
Fill an input field found by query with text.
Scroll a UI element into view.
Output schemas not documented. Tools return values but expected return types (fields, structure, pagination) are not explicitly specified in the visible code. This forces LLMs to infer output structure and plan downstream actions without certainty.
Minimal descriptions on utility tools. Tools like 'mouse_scroll', 'keyboard_type', 'clipboard_get', 'get_screen_size', 'get_mouse_position', 'get_last_error' have descriptions under 80 characters with limited context on when/why to use them or what they return. Production guidance requires 50-200 character descriptions with purpose and use cases.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-21 | C | 61 | 2026-07-28+ | v2 |
| 2026-03-09 | D | 55 | - | v1 |
Execute a shell command in the session.
Find UI elements matching a search query and/or required AT-SPI2 states. Returns a list of matching elements with their role, name, bounding box (x, y, width, height), and available actions. Use this to locate specific buttons, inputs, or labels before clicking or interacting.
Get the accessibility tree as structured JSON.
Get the last error message.
Get the current mouse cursor position.
Get the virtual screen dimensions.
Get information about the current session.
Press a key or key combination.
Press a keyboard shortcut (multiple keys at once).
Type text into the focused input field.
List accessible application windows with titles and active/focused state.
Click at coordinates in the isolated session. Coordinates use the virtual screen pixel grid where (0, 0) is the top-left corner. Returns a description of the click performed. Optionally captures screenshot frames after the click for visual feedback.
Move the mouse cursor to coordinates without clicking. Use this to trigger hover effects, reveal tooltips, or position the cursor before a separate button-down action.
Scroll the mouse wheel at coordinates.
Capture a screenshot of the isolated session. Requires an active session. Returns the file path to the saved PNG image and its size in KB.
Connect to an existing KWin session (e.g. the real desktop or a container). Only use when explicitly asked to interact with a real/existing desktop session. For normal GUI automation, use session_start instead (creates an isolated virtual session). This connects to a KWin compositor that is already running. Clipboard is always available. Input injection uses KWin EIS when possible, with ydotool as fallback.
Check if a session is currently running.
Start an isolated KWin Wayland session, optionally launching an app. This must be called before any other tool. If a session is already running, call session_stop first. Returns session status including the Wayland socket path, launched app PID (if any), and input backend availability.
Stop the current session and clean up. For virtual sessions: terminates KWin, all launched apps, and the D-Bus session. For live sessions: disconnects without killing KWin or pre-existing apps. Cleans up temporary files and clipboard processes. Safe to call when no session is running (returns "No session running.").
Enable or disable virtual keyboard.
Poll for a UI element matching a query and/or required states until found or timeout.
Poll for a window matching a title until found or timeout.
No error classification or recovery guidance. Error responses (via 'get_last_error' pattern) do not provide categorization (retryable vs user-fixable vs fatal) or actionable next steps. LLMs lack guidance on whether to retry, ask the user, or abandon the attempt.
Dry-run or confirmation pattern missing for destructive operations. Tools like 'session_stop', 'execute_command', and 'clear_error' modify state but lack a dry-run or pre-confirmation mechanism. Agents may accidentally stop sessions or execute commands irreversibly.
Limited parameter range documentation. Numeric parameters like 'screen_width', 'screen_height', 'max_depth', 'timeout_ms', 'poll_interval_ms' lack explicit min/max constraints in descriptions. LLMs may pass unreasonable values (negative width, 1ms polling interval) without guidance.
No idempotency guarantees documented. Tools like 'mouse_click', 'keyboard_type', 'execute_command' perform actions that, when retried, may cause duplicate side effects (clicking twice, typing twice, running a command twice). Expected idempotency or retry safety should be documented.