kwin-mcp
An MCP server with 29 tools that runs Wayland apps in a virtual KDE Plasma 6 session and reads the accessibility tree
- 80 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- In live mode the agent presses buttons and types into real apps on your desktop and uses the clipboard
- Virtual session isolation covers only windows and input: launched apps still see your files and network
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/kwin-mcpDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- In live mode the agent presses buttons and types into real apps on your desktop and uses the clipboard
- Virtual session isolation covers only windows and input: launched apps still see your files and network
This is third-party code. Review the repository files before installing.
What it does
kwin-mcp is an MCP server for GUI automation on Linux with KDE Plasma 6 on Wayland. An agent launches any Wayland application in an isolated virtual session with its own `kwin_wayland --virtual` compositor, leaving your desktop alone: your windows and input stay separate. The server has 29 tools: session management, app launch and logs, screenshots, the AT-SPI2 accessibility tree, windows, mouse, keyboard, touch, clipboard and D-Bus. Interface elements arrive structured, with roles and coordinates, so screenshots are not needed to act. A mode also attaches to a live desktop or to KWin in a container. A `kwin-desktop-automation` skill ships with the MCP.
Who it is for. Developers of Qt, GTK and Electron apps on KDE Plasma who need end-to-end tests in CI, and Linux users who give an agent control of programs.
Good fit when
- You write end-to-end tests for a Qt app and run them with no physical display
- The agent must launch `kcalc`, press buttons and confirm the result with a screenshot
- CI on GitHub Actions or GitLab needs a UI check on Linux
- You share your desktop with the agent and ask it to walk through settings with you
- A kiosk or embedded device on KDE needs automatic scenario runs
Not a fit when
- You use Windows, macOS or Linux without KDE Plasma 6 on Wayland: the server relies on private KWin interfaces
- You need a file and network sandbox: isolation covers only windows and input
- The agent must type in layouts other than US QWERTY without the clipboard fallback
- Requests go to a live desktop with unsaved work and you are not ready for window closes
Example request
Start a KWin session, launch kcalc, press the buttons to calculate 2 + 3 and take a screenshot of the resultMCP
- Transport
- stdio
- Authentication
- not required
Limitations
It needs KDE Plasma 6 on Wayland, Python 3.12 or newer and system packages: `libei1`, `spectacle`, `at-spi2-core`, plus a compiler to build PyGObject and dbus-python when installing through `uv` or `pip`. The `keys` typing method supports only US QWERTY; other characters go through the `unicode` method, which temporarily uses the clipboard. Isolation covers windows and input, not files or network, and it is not a security sandbox. In live mode actions affect real programs, and closing a window asks you for confirmation.
How to disable. Remove the `kwin-mcp` entry from `.mcp.json` or the plugin through `/plugin` and, if needed, run `uv tool uninstall kwin-mcp`. A running session ends with the `session_stop` tool.
FAQ
How do I connect kwin-mcp to Claude Code?
Add a server to `.mcp.json` with the `uvx` command and the `kwin-mcp` argument. Faster is the plugin: `/plugin marketplace add isac322/kwin-mcp` and `/plugin install kwin-mcp@kwin-mcp`, which also adds the skill.
Does the server touch my desktop?
Not in a virtual session: windows live in a separate compositor. In live mode actions hit the real desktop, enabled through `session_connect` or the `--default-live-session` flag.
Are screenshots needed for clicks?
No. The AT-SPI2 accessibility tree gives elements `ref` handles that any pointer or touch tool accepts as a target, and `element_act` invokes an action without coordinates.
What about non-English input?
`keyboard_type(method="keys")` accepts only US QWERTY. For other characters choose `method="unicode"`, which pastes text through the clipboard.
Can it run in CI?
Yes, a virtual session needs no X11 or physical display, so it suits Linux runners on GitHub Actions and GitLab when dependencies are installed.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server and CLI that give an agent its own hidden Linux desktop on X11 or Wayland without touching your screen or browser
A community Playwright MCP server: browser automation, screenshots, device emulation and test code generation
The official MCP server debugger: web UI, automation CLI and terminal UI in one package
kogiQA MCP gives an agent a browser that finds page elements without selectors, for debugging web apps and writing e2e tests
The official Testkube MCP server: an agent runs test workflows in Kubernetes and reads run logs, artifacts and metrics.
The npx @wong2/mcp-cli command runs MCP servers from a Claude Desktop config, lists their tools and calls them from the terminal.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| kwin-mcp (this card) | no | not required | 80 | |
| computer-use-linux | yes | not required | 867 | drives a generic Linux desktop; kwin-mcp works in an isolated KWin session and reads the accessibility tree |
| Open Computer Use | no | not required | 2,940 | a general computer-use agent; here a KDE Plasma 6 and Wayland focus with 29 typed tools |
README in short
The README lists features and use cases, installation steps with system dependencies, setup for Claude Code, OpenCode and other clients, server flags and all 29 tools with parameters. Separate sections cover architecture, requirements, migration from 0.11 and limitations.