kwin

kwin-mcp is a Model Context Protocol server that lets MCP clients (e.g., Claude Code, Cursor) interact with Linux GUI applications running inside isolated virtual KWin Wayland sessions. It exposes 29 MCP tools organized into three groups: session management, observation, and input/mouse control. Use session_start to spin up a new virtual KWin session and optionally launch an app; session_stop to cleanly tear down the session. You can capture screenshots with screenshot, inspect the accessibility tree with accessibility_tree, and find UI elements with find_ui_elements to drive UI actions based on roles, names, and states. Mouse and input tools (mouse_click, mouse_move, mouse_scroll, mouse_drag, and button events) enable precise control of UI interactions within the isolated session, while AT-SPI2 data provides structured widget information for robust automation without relying solely on vision data.

Prerequisites:

• Python 3.12+ and pip installed on your system
• KDE Plasma 6 running Wayland (for full functionality with KWin)
• Optional: a system with XDG compatible clipboard tools if you intend to use clipboard features

Installation steps:

1. Install kwin-mcp from PyPI

   • Using pip (recommended): pip install kwin-mcp

2. Verify installation (example):

   • Run the module directly to start the MCP server (see "Running Directly" in the project docs): python -m kwin_mcp

3. Alternative installation via uv (optional):

   • Install via uv tool management (if you prefer uvx/uv tool workflow): uv tool install kwin-mcp
   • Run via uvx: uvx kwin-mcp

4. Configuration (example for .mcp.json in your project): { "mcpServers": { "kwin-mcp": { "command": "python", "args": ["-m", "kwin_mcp"] } } }

Note: If you install the CLI entry points, you can also run:

• kwin-mcp
• python -m kwin_mcp
• kwin-mcp-cli

These commands will start the MCP server in the current environment.

Tips and considerations:

• kwin-mcp runs each session in an isolated manner (dbus-run-session + kwin_wayland --virtual), ensuring your host desktop is unaffected.
• For clipboard support inside sessions, enable clipboard tools like wl-clipboard (needed if you want clipboard interactions).
• The server uses the AT-SPI2 accessibility tree to provide structured UI data, so some actions may rely on accessibility support being present in target applications.
• If you encounter issues with rendering or input in virtual sessions, ensure your system has KDE Plasma 6 Wayland and necessary KWin components installed and that virtualization features are enabled in your GPU drivers.
• To integrate into CI/CD or automation pipelines, leverage the 2-3 piece workflow: start a session (session_start), perform automated UI actions (via mouse/keyboard tools and element discovery), then stop the session (session_stop) to clean up resources.