kwin-mcp

kwin-mcp

Model Context Protocol server for Linux desktop GUI automation on KDE Plasma 6 Wayland

Actively maintained fork of 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 and releases. Install: uv tool install git+https://github.com/VibeProgramm/kwin-mcp

A Model Context Protocol (MCP) 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.

Table of Contents

• Why kwin-mcp?
• Use Cases
• Quick Start
• Configuration
• Available Tools
• How It Works
• System Requirements
• Installation
• Limitations
• Contributing
• License

Why kwin-mcp?

• Isolated sessions -- Each session runs in its own dbus-run-session + kwin_wayland --virtual sandbox. Your host desktop is never affected.
• 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.
• 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.
• Zero authorization prompts -- Uses KWin's private EIS (Emulated Input Server) D-Bus interface directly, bypassing the XDG RemoteDesktop portal. No user confirmation dialogs.
• 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.
• Full input coverage -- Mouse, keyboard, multi-touch, and clipboard -- all injected through the isolated session for complete desktop automation.

Use Cases

Automated GUI Testing

Run 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.

AI-Driven Desktop Automation

Let 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.

Live Desktop Collaboration

Connect 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.

Headless GUI Testing in CI/CD

Integrate 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.

Kiosk and Embedded Device Automation

Automate 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.

Quick Start

Requires KDE Plasma 6 on Wayland. See System Requirements for details.

1. Install

# Using uv (recommended)

uv tool install git+https://github.com/VibeProgramm/kwin-mcp

Or from a source checkout

git clone https://github.com/VibeProgramm/kwin-mcp.git cd kwin-mcp uv tool install .

2. Configure Claude Code

Add to your project's .mcp.json:

{

"mcpServers": { "kwin-mcp": { "command": "uvx", "args": ["kwin-mcp"] } } }

3. Use it

Ask Claude Code to launch and interact with any GUI application:

Start a KWin session, launch kcalc, and press the buttons to calculate 2 + 3.

Claude 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.

Configuration

Recommended: install as a plugin

The 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).

Claude Code — install the plugin from the marketplace:

/plugin marketplace add VibeProgramm/kwin-mcp

/plugin install kwin-mcp@kwin-mcp

OpenCode — add the npm plugin to your opencode.json:

{

"$schema": "https://opencode.ai/config.json", "plugin": ["@isac322/kwin-mcp-opencode"] }

For the full integration guide (manual fallback, customising the skill, troubleshooting), see docs/ai-agent-integration.md.

Claude Code

Add to your project's .mcp.json:

{

"mcpServers": { "kwin-mcp": { "command": "uvx", "args": ["kwin-mcp"] } } }

Or if installed globally:

{

"mcpServers": { "kwin-mcp": { "command": "kwin-mcp" } } }

Claude Desktop

Add to your claude_desktop_config.json:

{

"mcpServers": { "kwin-mcp": { "command": "uvx", "args": ["kwin-mcp"] } } }

Running Directly

# As an installed script

kwin-mcp

As a Python module

python -m kwin_mcp

Interactive CLI (REPL for rapid testing)

kwin-mcp-cli

Live session mode (default to real desktop instead of virtual)

kwin-mcp --default-live-session kwin-mcp-cli --default-live-session

Available Tools

Session Management (3 tools)

Observation (3 tools)

Mouse Input (6 tools)

Keyboard Input (5 tools)

| keyboard_key_down | key str | Press and hold a key without releasing. Useful for hold