[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_124":125},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":21,"_24":25,"_26":27,"_28":29,"_30":31,"_32":33,"_34":25,"_35":36,"_37":-5,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":45,"_47":48,"_49":50,"_51":52,"_53":-5,"_54":45,"_55":56,"_57":58,"_59":-5,"_60":-5,"_61":-5,"_62":-5,"_63":64,"_65":66,"_67":68,"_69":70,"_71":72,"_73":-5,"_74":-5,"_75":-5,"_76":45,"_77":-5,"_78":79,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89},"apiUrl","https://odel.app/api","creator","vibeprogramm","moduleId","kwin-mcp","@vibeprogramm/kwin-mcp","displayName","tagline","KDE Plasma 6 Wayland GUI automation for AI agents: 30 tools (EIS input, screenshots, AT-SPI2).","iconKey","https://avatars.githubusercontent.com/u/36777218?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1788776992000,"updatedAt","sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.VibeProgramm%2Fkwin-mcp","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",1,"upstreamUpdatedAt",1788766540000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/VibeProgramm/kwin-mcp","githubRepoFullName","VibeProgramm/kwin-mcp","releaseId","ext-vibeprogramm-kwin-mcp","version","0.8.2","descriptionMarkdown","# kwin-mcp\n\n**Model Context Protocol server for Linux desktop GUI automation on KDE Plasma 6 Wayland**\n\n> **Actively maintained fork** of [isac322/kwin-mcp](https://github.com/isac322/kwin-mcp). This fork ships the fixes users were waiting for: MCP Python SDK 2.x support, text input in virtual sessions (host keymap isolation), reliable window focus, bounded startup waits, silent input-drop fix, honest error contracts — see the [changelog](https://github.com/VibeProgramm/kwin-mcp/blob/main/CHANGELOG.md) and [releases](https://github.com/VibeProgramm/kwin-mcp/releases). Install: `uv tool install git+https://github.com/VibeProgramm/kwin-mcp`\n\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://github.com/VibeProgramm/kwin-mcp/blob/main/pyproject.toml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/VibeProgramm/kwin-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/VibeProgramm/kwin-mcp/actions/workflows/ci.yml)\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI agents (Claude Code, Cursor, and other MCP clients) to launch, interact with, and observe any Wayland application in a fully isolated virtual KWin session -- without affecting the user's desktop. It also supports **live desktop automation** by connecting to an existing KWin session (real desktop or container) for collaborative workflows. With 30 MCP tools covering mouse, keyboard, touch, clipboard, accessibility tree inspection, screenshot capture, and window management, kwin-mcp provides everything needed for end-to-end GUI testing and desktop automation on Linux.\n\n## Table of Contents\n\n- [Why kwin-mcp?](#why-kwin-mcp)\n- [Use Cases](#use-cases)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Available Tools](#available-tools)\n- [How It Works](#how-it-works)\n- [System Requirements](#system-requirements)\n- [Installation](#installation)\n- [Limitations](#limitations)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Why kwin-mcp?\n\n- **Isolated sessions** -- Each session runs in its own `dbus-run-session` + `kwin_wayland --virtual` sandbox. Your host desktop is never affected.\n- **Live session support** -- Connect to a real KDE Plasma desktop or a KWin instance inside a container (e.g. `systemd-nspawn`) for collaborative \"share my screen\" workflows.\n- **No screenshots required for interaction** -- The AT-SPI2 accessibility tree gives the AI agent structured widget data (roles, names, coordinates, states, available actions), so it can interact with UI elements without relying solely on vision.\n- **Zero authorization prompts** -- Uses KWin's private EIS (Emulated Input Server) D-Bus interface directly, bypassing the XDG RemoteDesktop portal. No user confirmation dialogs.\n- **Works with any Wayland app** -- Anything that runs on KDE Plasma 6 Wayland works: Qt, GTK, Electron, and more. Input is injected via the standard `libei` protocol.\n- **Full input coverage** -- Mouse, keyboard, multi-touch, and clipboard -- all injected through the isolated session for complete desktop automation.\n\n## Use Cases\n\n### Automated GUI Testing\n\nRun end-to-end GUI tests for KDE/Qt/GTK applications in headless isolated sessions. kwin-mcp launches each app in its own virtual KWin compositor, interacts via mouse, keyboard, and touch input, then verifies results through screenshots and the accessibility tree -- all without a physical display.\n\n### AI-Driven Desktop Automation\n\nLet AI agents like Claude Code autonomously operate desktop applications. The agent reads the accessibility tree to understand the UI, performs actions through 30 MCP tools, and observes the results via screenshots -- creating a complete feedback loop for any Wayland application.\n\n### Live Desktop Collaboration\n\nConnect to your real desktop session and let Claude observe and interact with what you see. Use `session_connect` or pass `--default-live-session` to make live mode the default. Also supports attaching to KWin running inside containers (e.g. `systemd-nspawn`) for isolated agent desktops.\n\n### Headless GUI Testing in CI/CD\n\nIntegrate Linux desktop GUI testing into CI/CD pipelines. kwin-mcp's virtual sessions require no X11 or physical display server, making it suitable for headless environments like GitHub Actions or GitLab CI runners on Linux.\n\n### Kiosk and Embedded Device Automation\n\nAutomate kiosk interfaces and embedded Linux desktops running KDE Plasma or a bare KWin Wayland compositor. Use `session_start` for isolated virtual testing of kiosk UIs, or `session_connect` to attach directly to a live kiosk or embedded device session for real-time automation and diagnostics.\n\n## Quick Start\n\n> Requires KDE Plasma 6 on Wayland. See [System Requirements](#system-requirements) for details.\n\n**1. Install**\n\n```bash\n# Using uv (recommended)\nuv tool install git+https://github.com/VibeProgramm/kwin-mcp\n\n# Or from a source checkout\ngit clone https://github.com/VibeProgramm/kwin-mcp.git\ncd kwin-mcp\nuv tool install .\n```\n\n**2. Configure Claude Code**\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"kwin-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"kwin-mcp\"]\n }\n }\n}\n```\n\n**3. Use it**\n\nAsk Claude Code to launch and interact with any GUI application:\n\n```\nStart a KWin session, launch kcalc, and press the buttons to calculate 2 + 3.\n```\n\nClaude Code will autonomously start an isolated session, launch the app, read the accessibility tree to find buttons, click them, and take a screenshot to verify the result.\n\n## Configuration\n\n### Recommended: install as a plugin\n\nThe fastest way to wire kwin-mcp into your editor is to install one of the bundled plugins. Each plugin auto-registers the MCP server **and** ships the `kwin-desktop-automation` skill, which teaches the agent which tool to call when (session-mode selection, the observe → act → verify loop, US-QWERTY vs Unicode typing, AT-SPI2 coordinate translation, and other platform pitfalls).\n\n**Claude Code** — install the plugin from the marketplace:\n\n```text\n/plugin marketplace add VibeProgramm/kwin-mcp\n/plugin install kwin-mcp@kwin-mcp\n```\n\n**OpenCode** — add the npm plugin to your `opencode.json`:\n\n```jsonc\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"plugin\": [\"@isac322/kwin-mcp-opencode\"]\n}\n```\n\nFor the full integration guide (manual fallback, customising the skill, troubleshooting), see [docs/ai-agent-integration.md](https://github.com/VibeProgramm/kwin-mcp/blob/main/docs/ai-agent-integration.md).\n\n### Claude Code\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"kwin-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"kwin-mcp\"]\n }\n }\n}\n```\n\nOr if installed globally:\n\n```json\n{\n \"mcpServers\": {\n \"kwin-mcp\": {\n \"command\": \"kwin-mcp\"\n }\n }\n}\n```\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"kwin-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"kwin-mcp\"]\n }\n }\n}\n```\n\n### Running Directly\n\n```bash\n# As an installed script\nkwin-mcp\n\n# As a Python module\npython -m kwin_mcp\n\n# Interactive CLI (REPL for rapid testing)\nkwin-mcp-cli\n\n# Live session mode (default to real desktop instead of virtual)\nkwin-mcp --default-live-session\nkwin-mcp-cli --default-live-session\n```\n\n## Available Tools\n\n### Session Management (3 tools)\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `session_start` | `app_command?` `str`, `screen_width?` `int` (1920), `screen_height?` `int` (1080), `enable_clipboard?` `bool` (false), `keep_screenshots?` `bool` (false), `isolate_home?` `bool` (false), `keep_home?` `bool` (false), `env?` `dict` | Start an isolated KWin Wayland session, optionally launching an app. Set `enable_clipboard=true` to enable clipboard tools (requires `wl-clipboard`). Set `keep_screenshots=true` to preserve screenshot files after `session_stop`. Set `isolate_home=true` to create a temporary HOME with isolated XDG directories (config, data, cache, state), preventing apps from reading/writing host user settings. Set `keep_home=true` to preserve the isolated home directory after `session_stop`. Pass extra environment variables via `env`. |\n| `session_connect` | `dbus_address?` `str`, `wayland_display?` `str`, `keep_screenshots?` `bool` (false) | Connect to an existing KWin session (real desktop or container). Defaults to `$DBUS_SESSION_BUS_ADDRESS` and `$WAYLAND_DISPLAY`. Clipboard is always enabled. `session_stop` only disconnects without killing KWin or pre-existing apps. |\n| `session_stop` | _(none)_ | Stop the session and clean up. For virtual sessions: terminates KWin and all apps. For live sessions: disconnects without killing KWin or pre-existing apps. |\n\n### Observation (3 tools)\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `screenshot` | `include_cursor?` `bool` (false) | Capture a screenshot of the virtual display (saved as PNG, returns file path) |\n| `accessibility_tree` | `app_name?` `str`, `max_depth?` `int` (15), `role?` `str` | Get the AT-SPI2 widget tree with roles, names, states, and screen coordinates (translated from window-local coordinates via compositor-side window geometry). Use `role` to filter to specific element types (e.g. `\"button\"`, `\"check box\"`). Non-matching elements are hidden but their children are still traversed. |\n| `find_ui_elements` | `query` `str`, `app_name?` `str`, `states?` `list[str]` | Search for UI elements by name, role, or description (case-insensitive). Returns screen coordinates suitable for `mouse_click` and friends. Optionally filter by AT-SPI2 states (e.g. `[\"focused\"]`, `[\"active\", \"visible\"]`). `query` can be empty when filtering by states only. |\n\n### Mouse Input (6 tools)\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `mouse_click` | `x` `int`, `y` `int`, `button?` `str` (\"left\"), `double?` `bool`, `triple?` `bool`, `modifiers?` `list[str]`, `hold_ms?` `int` (0), `screenshot_after_ms?` `list[int]` | Click at coordinates. Supports left/right/middle, single/double/triple click, modifier keys (e.g. `[\"ctrl\", \"shift\"]`), and long-press via `hold_ms`. |\n| `mouse_move` | `x` `int`, `y` `int`, `screenshot_after_ms?` `list[int]` | Move the cursor (hover) to coordinates without clicking |\n| `mouse_scroll` | `x` `int`, `y` `int`, `delta` `int`, `horizontal?` `bool`, `discrete?` `bool`, `steps?` `int` (1) | Scroll at coordinates. `delta` positive = down/right, negative = up/left. Use `discrete=true` for wheel ticks, `steps` to split into smooth increments. |\n| `mouse_drag` | `from_x` `int`, `from_y` `int`, `to_x` `int`, `to_y` `int`, `button?` `str` (\"left\"), `modifiers?` `list[str]`, `waypoints?` `list[[x,y,dwell_ms]]`, `screenshot_after_ms?` `list[int]` | Drag from one point to another with smooth interpolation. Supports custom `waypoints` for complex drag paths. |\n| `mouse_button_down` | `x` `int`, `y` `int`, `button?` `str` (\"left\") | Press a mouse button at coordinates without releasing. Use with `mouse_button_up` for manual drag control. |\n| `mouse_button_up` | `x` `int`, `y` `int`, `button?` `str` (\"left\") | Release a previously pressed mouse button at coordinates |\n\n### Keyboard Input (5 tools)\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `keyboard_type` | `text` `str`, `screenshot_after_ms?` `list[int]` | Type a string of text character by character (US QWERTY layout) |\n| `keyboard_type_unicode` | `text` `str`, `screenshot_after_ms?` `list[int]` | Type arbitrary Unicode text (Korean, CJK, etc.) via `wtype` or clipboard fallback (`wl-copy` + Ctrl+V). Requires `wtype` or `wl-clipboard` installed. |\n| `keyboard_key` | `key` `str`, `screenshot_after_ms?` `list[int]` | Press a key or key combination (e.g., `Return`, `ctrl+c`, `alt+F4`, `shift+Tab`) |\n| `keyboard_key_down` | `key` `str` | Press and hold a key without releasing. Useful for holding modifiers across multiple actions (e.g., hold Ctrl while clicking items). |\n| `keyboard_key_up` | `key` `str` | Release a previously held key |\n\n### Touch Input (4 tools)\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `touch_tap` | `x` `int`, `y` `int`, `hold_ms?` `int` (0), `screenshot_after_ms?` `list[int]` | Tap at coordinates. Use `hold_ms` for long-press gestures. |\n| `touch_swipe` | `from_x` `int`, `from_y` `int`, `to_x` `int`, `to_y` `int`, `duration_ms?` `int` (300), `screenshot_after_ms?` `list[int]` | Swipe from one point to another with configurable duration |\n| `touch_pinch` | `center_x` `int`, `center_y` `int`, `start_distance` `int`, `end_distance` `int`, `duration_ms?` `int` (500), `screenshot_after_ms?` `list[int]` | Two-finger pinch gesture. `end_distance < start_distance` = pinch in, `end_distance > start_distance` = pinch out. |\n| `touch_multi_swipe` | `from_x` `int`, `from_y` `int`, `to_x` `int`, `to_y` `int`, `fingers?` `int` (3), `duration_ms?` `int` (300), `screenshot_after_ms?` `list[int]` | Multi-finger swipe gesture (2-5 fingers) for system gestures like workspace switching |\n\n### Clipboard (2 tools)\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `clipboard_get` | _(none)_ | Read the current clipboard text content. Requires `enable_clipboard=true` in `session_start` and `wl-clipboard` installed. |\n| `clipboard_set` | `text` `str` | Set the clipboard text content. Same requirements as `clipboard_get`. |\n\n### Window Management (3 tools)\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `launch_app` | `command` `str`, `env?` `dict` | Launch an application inside the running session. Returns PID and log path. |\n| `list_windows` | _(none)_ | List all accessible application windows with per-window titles and active/focused state markers via AT-SPI2 |\n| `focus_window` | `app_name` `str` | Focus a window by application name (case-insensitive match) |\n\n### UI Polling (1 tool)\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `wait_for_element` | `query` `str`, `app_name?` `str`, `timeout_ms?` `int` (5000), `poll_interval_ms?` `int` (200), `expected_states?` `list[str]` | Poll the accessibility tree until an element matching the query and/or states appears or timeout expires. Use `expected_states` to wait for state changes (e.g. `[\"active\"]`, `[\"checked\"]`). `query` can be empty when waiting for state changes only. |\n\n### Advanced (3 tools)\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `dbus_call` | `service` `str`, `path` `str`, `interface` `str`, `method` `str`, `args?` `list[str]` | Call any D-Bus method in the isolated session. Useful for controlling KWin scripting, app-specific D-Bus APIs, and system services. |\n| `read_app_log` | `pid` `int`, `last_n_lines?` `int` (50) | Read stdout/stderr output of a launched app by PID. Set `last_n_lines=0` for all output. |\n| `wayland_info` | `filter_protocol?` `str` | List Wayland protocols available in the session. Useful for verifying protocol access (e.g., `plasma_window_management`). |\n\n> **Frame capture:** Many action tools accept an optional `screenshot_after_ms` parameter (e.g., `[0, 50, 100, 200, 500]`) that captures screenshots at specified delays (in milliseconds) after the action completes. This is useful for observing transient UI states like hover effects, click animations, and menu transitions without extra MCP round-trips. Frame capture uses the fast KWin ScreenShot2 D-Bus interface (~30-70ms per frame).\n\n## How It Works\n\n```\nClaude Code / AI Agent\n |\n | MCP (stdio)\n v\nkwin-mcp server (30 tools) kwin-mcp-cli (interactive REPL)\n | |\n +--- both delegate to AutomationEngine (core.py) ---+\n |\n |-- session_start (virtual) ---> dbus-run-session\n | |-- at-spi-bus-launcher\n | +-- kwin_wayland --virtual\n | +-- [your app]\n |\n |-- session_connect (live) ----> existing KWin (real desktop / container)\n |\n |-- screenshot ---------------> KWin ScreenShot2 D-Bus (spectacle fallback)\n |\n |-- accessibility_tree -------> AT-SPI2 (via PyGObject)\n |-- find_ui_elements ---------> AT-SPI2 (via PyGObject)\n |-- wait_for_element ----------> AT-SPI2 (polling)\n |\n |-- mouse_* ------------------> KWin EIS D-Bus --> libei\n |-- keyboard_* ---------------> KWin EIS D-Bus --> libei\n |-- touch_* ------------------> KWin EIS D-Bus --> libei\n | +-- screenshot_after_ms -> KWin ScreenShot2 D-Bus (fast frame capture)\n |\n |-- keyboard_type_unicode ----> wtype / wl-copy + Ctrl+V\n |-- clipboard_* --------------> wl-copy / wl-paste (wl-clipboard)\n |\n |-- launch_app / list_windows / focus_window\n | |-- subprocess spawn\n | +-- AT-SPI2 (via PyGObject)\n |\n |-- dbus_call -----------------> dbus-send (generic D-Bus)\n |-- read_app_log --------------> log file read\n +-- wayland_info --------------> wayland-info\n```\n\n### Triple Isolation (+ Optional Home Isolation)\n\nkwin-mcp provides three layers of isolation from the host desktop:\n\n1. **D-Bus isolation** -- `dbus-run-session` creates a private session bus. The isolated session's services (KWin, AT-SPI2, portals) are invisible to the host.\n2. **Display isolation** -- `kwin_wayland --virtual` creates its own Wayland compositor with a virtual framebuffer. No windows appear on the host display.\n3. **Input isolation** -- Input events are injected through KWin's EIS interface into the isolated compositor only. The host desktop receives no input from kwin-mcp.\n4. **Home directory isolation** (optional) -- When `isolate_home=true` is set in `session_start`, a temporary HOME directory is created with isolated XDG directories (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_CACHE_HOME`, `XDG_STATE_HOME`). Apps in the session cannot read or modify host user settings (e.g. `~/.config/kdeglobals`), improving test reproducibility and safety. `XDG_RUNTIME_DIR` is intentionally not isolated because the Wayland socket resides there.\n\n### Input Injection\n\nMouse, keyboard, and touch events are injected through KWin's private `org.kde.KWin.EIS.RemoteDesktop` D-Bus interface. This returns a `libei` file descriptor that allows low-level input emulation without requiring the XDG RemoteDesktop portal (which would show a user authorization dialog). The connection uses:\n\n- **Absolute pointer positioning** for precise coordinate-based interaction\n- **evdev keycodes** with full US QWERTY mapping for keyboard input\n- **Smooth drag interpolation** (10+ intermediate steps) for realistic drag operations\n- **EIS touch emulation** for multi-touch gestures (tap, swipe, pinch, multi-finger swipe)\n\n### Screenshot Capture\n\nThe `screenshot` tool captures via the KWin `org.kde.KWin.ScreenShot2` D-Bus interface (~30-70ms per frame), with `spectacle` CLI as a fallback. For action tools with the `screenshot_after_ms` parameter, the same D-Bus interface is used for fast burst capture. Raw ARGB pixel data is read from a pipe and converted to PNG using Pillow.\n\n### Accessibility Tree\n\nThe AT-SPI2 accessibility bus within the isolated session is queried via PyGObject (`gi.repository.Atspi`). This provides a structured tree of all UI widgets with their roles (button, text field, menu item, etc.), names, states (focused, enabled, visible, etc.), screen coordinates, and available actions (click, toggle, etc.).\n\n## System Requirements\n\n| Requirement | Details |\n|-------------|---------|\n| **OS** | Linux with KDE Plasma 6 (Wayland session) |\n| **Python** | 3.12 or later |\n| **KWin** | `kwin_wayland` with `--virtual` flag support (KDE Plasma 6.x) |\n| **libei** | Usually bundled with KWin 6.x (EIS input emulation) |\n| **spectacle** | KDE screenshot tool (CLI mode) |\n| **AT-SPI2** | `at-spi2-core` for accessibility tree support |\n| **PyGObject** | GObject introspection Python bindings |\n| **D-Bus** | `dbus-python` bindings |\n\n**Optional dependencies:**\n\n| Package | Required for |\n|---------|-------------|\n| `wl-clipboard` (`wl-copy`, `wl-paste`) | `clipboard_get`, `clipboard_set`, and `keyboard_type_unicode` clipboard fallback |\n| `wtype` | `keyboard_type_unicode` (preferred over clipboard fallback) |\n| `wayland-utils` (`wayland-info`) | `wayland_info` tool |\n\n### Installing System Dependencies\n\n

Arch Linux / Manjaro

\n\n```bash\nsudo pacman -S kwin spectacle at-spi2-core python-gobject dbus-python-common\n\n# Optional: for clipboard and Unicode input\nsudo pacman -S wl-clipboard wtype wayland-utils\n```\n\n

\n\n

Fedora (KDE Spin)

\n\n```bash\nsudo dnf install kwin-wayland spectacle at-spi2-core python3-gobject dbus-python\n\n# Optional: for clipboard and Unicode input\nsudo dnf install wl-clipboard wtype wayland-utils\n```\n\n

\n\n

openSUSE (KDE)

\n\n```bash\nsudo zypper install kwin6 spectacle at-spi2-core python3-gobject python3-dbus-python\n\n# Optional: for clipboard and Unicode input\nsudo zypper install wl-clipboard wtype wayland-utils\n```\n\n

\n\n

Kubuntu / KDE Neon

\n\n```bash\nsudo apt install kwin-wayland spectacle at-spi2-core python3-gi gir1.2-atspi-2.0 python3-dbus\n\n# Optional: for clipboard and Unicode input\nsudo apt install wl-clipboard wtype wayland-utils\n```\n\n

\n\n## Installation\n\n> **Note**: the `kwin-mcp` name on PyPI tracks the upstream project (`isac322/kwin-mcp`, v0.7.0, MCP SDK 1.x). This repository is the actively maintained fork (v0.8.2, MCP SDK 2.x); install it from git or from a source checkout. The `uvx kwin-mcp` config examples in the [Configuration](#configuration) section resolve to the PyPI package.\n\n### Using uv (recommended)\n\n```bash\nuv tool install git+https://github.com/VibeProgramm/kwin-mcp\n```\n\n### Using pip\n\n```bash\npip install git+https://github.com/VibeProgramm/kwin-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/VibeProgramm/kwin-mcp.git\ncd kwin-mcp\nuv sync\nuv run kwin-mcp\n```\n\n## Limitations\n\n- **US QWERTY keyboard layout only** -- `keyboard_type` supports US QWERTY only. For non-ASCII text (Korean, CJK, etc.), use `keyboard_type_unicode`, which requires `wtype` or `wl-clipboard` installed.\n- **KDE Plasma 6+ required** -- Older KDE versions or other Wayland compositors (GNOME, Sway) are not supported.\n- **AT-SPI2 availability varies** -- Some applications may not fully expose their widget tree via AT-SPI2.\n- **Touch input is EIS-emulated** -- Touch events are emulated through KWin's EIS interface, not from a real touchscreen device. Most applications handle emulated touch correctly, but some may behave differently from physical touch.\n- **Clipboard requires opt-in** -- Clipboard tools (`clipboard_get`, `clipboard_set`) are disabled by default because `wl-copy` can hang in isolated sessions. Enable with `enable_clipboard=true` in `session_start`, and ensure `wl-clipboard` is installed.\n- **QMenu (native context menus) may not appear in AT-SPI2** -- Qt's AT-SPI2 bridge has incomplete support for popup menus on Wayland. Context menus may not be visible in `accessibility_tree` or `find_ui_elements`. Workaround: use `screenshot` to visually locate menu items and click by coordinates.\n- **Screen edge triggers do not work with EIS input** -- Auto-hide panels and layer-shell trigger strips rely on Wayland surface input routing, which may not respond to EIS-injected pointer events. Workaround: use `dbus_call` with KWin scripting or keyboard shortcuts instead.\n- **AT-SPI2 coordinate translation is best-effort** -- Wayland clients report window-local coordinates (they do not know their global screen position by design). kwin-mcp translates them to true screen coordinates using each window's compositor-side geometry (queried from KWin scripting, matched by caption). If a window cannot be matched, its coordinates fall back to window-local -- cross-reference with `screenshot` to disambiguate.\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](https://github.com/VibeProgramm/kwin-mcp/blob/main/CONTRIBUTING.md) for development setup, code style guidelines, and the pull request process.\n\n```bash\ngit clone https://github.com/VibeProgramm/kwin-mcp.git\ncd kwin-mcp\nuv sync\nuv run ruff check src/\nuv run ruff format --check src/\nuv run ty check src/\n```\n\n## License\n\n[MIT](https://github.com/VibeProgramm/kwin-mcp/blob/main/LICENSE)\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_107":108,"_109":110,"_111":112,"_113":114,"_115":116,"_117":118},"requiredSecrets",[],"tags",[92,93,94,95,96,97,98,99,100,101,102,103,104,105,106],"assets",[],"stats",{"_90":79,"_91":79},"ratingAvg","reviewCount","accessibility","ai-agents","at-spi2","claude-code","computer-use","desktop-automation","e2e-testing","gui-automation","headless-testing","kde","kwin","libei","linux","live-session","maintained-fork","topics",[92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,119,120,121,122,123],"license","MIT","language","Python","registryName","io.github.VibeProgramm/kwin-mcp","homepage","https://github.com/VibeProgramm/kwin-mcp/releases","packages",[],"mcp","mcp-server","model-context-protocol","opencode","wayland","ENV",{"_126":127,"_128":129,"_130":131},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]