kwin-mcp

kwin-mcp

适用于 KDE Plasma 6 Wayland 的 Linux 桌面 GUI 自动化 MCP 服务

isac322/kwin-mcp 的积极维护分支。此分支提供了用户期待已久的修复：支持 MCP Python SDK 2.x、在虚拟会话中输入文本（隔离主机键盘映射）、可靠地聚焦窗口、限制启动等待时间、修复输入被静默丢弃的问题，并提供准确的错误契约——详情请参阅更新日志和发布页面。安装：uv tool install git+https://github.com/VibeProgramm/kwin-mcp

一个模型上下文协议（MCP）服务，让 AI Agent（Claude Code、Cursor 和其他 MCP 客户端）能够在完全隔离的虚拟 KWin 会话中启动、操作和观察任意 Wayland 应用，而不会影响用户的桌面。它还支持实时桌面自动化：连接到现有的 KWin 会话（真实桌面或容器），以实现协作工作流。kwin-mcp 提供 30 个 MCP 工具，涵盖鼠标、键盘、触控、剪贴板、无障碍树检查、屏幕截图和窗口管理，可满足在 Linux 上进行端到端 GUI 测试和桌面自动化所需的一切。

目录

• 为什么选择 kwin-mcp？
• 使用场景
• 快速开始
• 配置
• 可用工具
• 工作原理
• 系统要求
• 安装
• 限制
• 参与贡献
• 许可证

为什么选择 kwin-mcp？

• 隔离会话 —— 每个会话都在独立的 dbus-run-session + kwin_wayland --virtual 沙盒中运行，不会影响你的主机桌面。
• 支持实时会话 —— 连接到真实的 KDE Plasma 桌面，或容器内的 KWin 实例（例如 systemd-nspawn），以支持协作式“共享我的屏幕”工作流。
• 交互无需截图 —— AT-SPI2 无障碍树会向 AI Agent 提供结构化的控件数据（角色、名称、坐标、状态和可用操作），因此无需仅依赖视觉识别即可与 UI 元素交互。
• 无需授权提示 —— 直接使用 KWin 的私有 EIS（模拟输入服务）D-Bus 接口，绕过 XDG RemoteDesktop 门户。不会出现用户确认对话框。
• 适用于任何 Wayland 应用 —— 任何能在 KDE Plasma 6 Wayland 上运行的应用都适用：Qt、GTK、Electron 等。输入通过标准 libei 协议注入。
• 全面支持输入 —— 鼠标、键盘、多点触控和剪贴板，全部通过隔离会话注入，实现完整的桌面自动化。

使用场景

自动化 GUI 测试

在无头隔离会话中，为 KDE/Qt/GTK 应用运行端到端 GUI 测试。kwin-mcp 会在各自独立的虚拟 KWin 合成器中启动应用，通过鼠标、键盘和触控输入执行操作，然后通过屏幕截图和无障碍树验证结果——整个过程无需物理显示器。

AI 驱动的桌面自动化

让 Claude Code 等 AI Agent 自主操作桌面应用。Agent 读取无障碍树以理解 UI，通过 30 个 MCP 工具执行操作，并通过屏幕截图观察结果，为任何 Wayland 应用构建完整的反馈循环。

实时桌面协作

连接到你的真实桌面会话，让 Claude 观察并操作你看到的内容。使用 session_connect，或传入 --default-live-session 将实时模式设为默认模式。也支持连接到容器（例如 systemd-nspawn）内运行的 KWin，以创建隔离的 Agent 桌面。

CI/CD 中的无头 GUI 测试

将 Linux 桌面 GUI 测试集成到 CI/CD 流水线中。kwin-mcp 的虚拟会话无需 X11 或物理显示服务器，因此适用于 GitHub Actions 或 Linux 上的 GitLab CI 运行器等无头环境。

信息亭和嵌入式设备自动化

自动化运行 KDE Plasma 或纯 KWin Wayland 合成器的设备信息亭界面和嵌入式 Linux 桌面。使用 session_start 对信息亭 UI 进行隔离的虚拟测试，或使用 session_connect 直接连接到实时信息亭或嵌入式设备会话，进行实时自动化和诊断。

快速开始

需要在 Wayland 上运行 KDE Plasma 6。详情请参阅系统要求。

1. 安装

# 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. 配置 Claude Code

将以下内容添加到项目的 .mcp.json：

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

3. 使用

让 Claude Code 启动并操作任意 GUI 应用：

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

Claude Code 会自主启动隔离会话、启动应用、读取辅助功能树以查找按钮、点击按钮，并截取屏幕截图来验证结果。

配置

推荐：安装为插件

将 kwin-mcp 接入编辑器的最快方式是安装一个随附插件。每个插件都会自动注册 MCP 服务，并且附带 kwin-desktop-automation 技能，指导 Agent 在何时调用哪个工具（会话模式选择、观察 → 操作 → 验证循环、US-QWERTY 与 Unicode 输入、AT-SPI2 坐标转换，以及其他平台注意事项）。

Claude Code — 从市场安装插件：

/plugin marketplace add VibeProgramm/kwin-mcp
/plugin install kwin-mcp@kwin-mcp

OpenCode — 将 npm 插件添加到 opencode.json：

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

完整的集成指南（手动备用方案、自定义技能、故障排除）请参阅 docs/ai-agent-integration.md。

Claude Code

将以下内容添加到项目的 .mcp.json：

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

如果是全局安装：

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

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

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

直接运行

# 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

可用工具

会话管理（3 个工具）

观察（3 个工具）

鼠标输入（6 个工具）

键盘输入（5 个工具）

触摸输入（4 个工具）

剪贴板（2 个工具）

窗口管理（3 个工具）

UI 轮询（1 个工具）

高级功能（3 个工具）

帧捕获： 许多操作工具都接受可选的 screenshot_after_ms 参数（例如 [0, 50, 100, 200, 500]），用于在操作完成后的指定延迟（毫秒）捕获屏幕截图。这有助于观察悬停效果、点击动画和菜单过渡等短暂的 UI 状态，而无需额外的 MCP 往返调用。帧捕获使用快速的 KWin ScreenShot2 D-Bus 接口（每帧约 30-70 毫秒）。

工作原理

Claude Code / AI Agent
  |
  |  MCP (stdio)
  v
kwin-mcp server  (30 tools)       kwin-mcp-cli (interactive REPL)
  |                                  |
  +--- both delegate to AutomationEngine (core.py) ---+
  |
  |-- session_start (virtual) ---> dbus-run-session
  |                                 |-- at-spi-bus-launcher
  |                                 +-- kwin_wayland --virtual
  |                                       +-- [your app]
  |
  |-- session_connect (live) ----> existing KWin (real desktop / container)
  |
  |-- screenshot ---------------> KWin ScreenShot2 D-Bus (spectacle fallback)
  |
  |-- accessibility_tree -------> AT-SPI2 (via PyGObject)
  |-- find_ui_elements ---------> AT-SPI2 (via PyGObject)
  |-- wait_for_element ----------> AT-SPI2 (polling)
  |
  |-- mouse_* ------------------> KWin EIS D-Bus --> libei
  |-- keyboard_* ---------------> KWin EIS D-Bus --> libei
  |-- touch_* ------------------> KWin EIS D-Bus --> libei
  |    +-- screenshot_after_ms -> KWin ScreenShot2 D-Bus (fast frame capture)
  |
  |-- keyboard_type_unicode ----> wtype / wl-copy + Ctrl+V
  |-- clipboard_* --------------> wl-copy / wl-paste (wl-clipboard)
  |
  |-- launch_app / list_windows / focus_window
  |                                |-- subprocess spawn
  |                                +-- AT-SPI2 (via PyGObject)
  |
  |-- dbus_call -----------------> dbus-send (generic D-Bus)
  |-- read_app_log --------------> log file read
  +-- wayland_info --------------> wayland-info

三重隔离（+ 可选的主目录隔离）

kwin-mcp 提供了与宿主桌面的三层隔离：

1. D-Bus 隔离——dbus-run-session 会创建一个私有会话总线。隔离会话的服务（KWin、AT-SPI2、portal）对宿主不可见。
2. 显示隔离——kwin_wayland --virtual 会使用虚拟帧缓冲区创建独立的 Wayland 合成器。宿主显示器上不会出现任何窗口。
3. 输入隔离——输入事件仅通过 KWin 的 EIS 接口注入隔离的合成器。宿主桌面不会收到来自 kwin-mcp 的输入。
4. 主目录隔离（可选）——在 session_start 中设置 isolate_home=true 时，会创建一个临时 HOME 目录，并使用隔离的 XDG 目录（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_CACHE_HOME、XDG_STATE_HOME）。会话中的应用无法读取或修改宿主用户设置（例如 ~/.config/kdeglobals），从而提高测试的可复现性和安全性。XDG_RUNTIME_DIR 不会被隔离，因为 Wayland 套接字位于此目录中。

输入注入

鼠标、键盘和触摸事件通过 KWin 的私有 org.kde.KWin.EIS.RemoteDesktop D-Bus 接口注入。此接口会返回一个 libei 文件描述符，从而无需使用 XDG RemoteDesktop portal（否则会显示用户授权对话框）即可进行低级别输入模拟。连接使用：

• 绝对指针定位，实现精准的坐标交互
• 用于键盘输入的 evdev 键码，支持完整的 US QWERTY 映射
• 平滑拖动插值（10 个以上中间步骤），实现逼真的拖动操作
• 用于多点触控手势（轻触、滑动、捏合、多指滑动）的 EIS 触摸模拟

屏幕截图

screenshot 工具通过 KWin 的 org.kde.KWin.ScreenShot2 D-Bus 接口捕获屏幕（每帧约 30–70 ms），并以 spectacle CLI 作为回退方案。对于带有 screenshot_after_ms 参数的操作工具，会使用相同的 D-Bus 接口快速连续捕获。原始 ARGB 像素数据会从管道读取，并使用 Pillow 转换为 PNG。

无障碍树

通过 PyGObject（gi.repository.Atspi）查询隔离会话中的 AT-SPI2 无障碍总线。此总线会提供所有 UI 组件的结构化树，包含其角色（按钮、文本框、菜单项等）、名称、状态（已聚焦、已启用、可见等）、屏幕坐标和可用操作（点击、切换等）。

系统要求

可选依赖项：

安装系统依赖项

sudo pacman -S kwin spectacle at-spi2-core python-gobject dbus-python-common

# Optional: for clipboard and Unicode input
sudo pacman -S wl-clipboard wtype wayland-utils

sudo dnf install kwin-wayland spectacle at-spi2-core python3-gobject dbus-python

# Optional: for clipboard and Unicode input
sudo dnf install wl-clipboard wtype wayland-utils

sudo zypper install kwin6 spectacle at-spi2-core python3-gobject python3-dbus-python

# Optional: for clipboard and Unicode input
sudo zypper install wl-clipboard wtype wayland-utils

sudo apt install kwin-wayland spectacle at-spi2-core python3-gi gir1.2-atspi-2.0 python3-dbus

# Optional: for clipboard and Unicode input
sudo apt install wl-clipboard wtype wayland-utils

注意：PyPI 上的 kwin-mcp 名称对应上游项目（isac322/kwin-mcp，v0.7.0，MCP SDK 1.x）。本仓库是积极维护的分支（v0.9.0，MCP SDK 2.x）；请从 git 或源代码检出安装。配置部分中的 uvx kwin-mcp 配置示例指向 PyPI 包。

使用 uv（推荐）

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

使用 pip

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

从源代码安装

git clone https://github.com/VibeProgramm/kwin-mcp.git
cd kwin-mcp
uv sync
uv run kwin-mcp

限制

• 仅支持美式 QWERTY 键盘布局——keyboard_type 仅支持美式 QWERTY。对于非 ASCII 文本（韩文、CJK 等），请使用 keyboard_type_unicode，该功能需要安装 wtype 或 wl-clipboard。
• 需要 KDE Plasma 6 或更高版本——不支持较旧的 KDE 版本或其他 Wayland 合成器（GNOME、Sway）。
• AT-SPI2 的可用性因应用而异——某些应用可能无法通过 AT-SPI2 完整公开其控件树。
• 触摸输入由 EIS 模拟——触摸事件通过 KWin 的 EIS 接口模拟，并非来自真实触摸屏设备。大多数应用都能正确处理模拟触摸，但某些应用的行为可能与实际触摸不同。
• 剪贴板需要主动启用——剪贴板工具（clipboard_get、clipboard_set）默认禁用，因为 wl-copy 在隔离会话中可能会挂起。请在 session_start 中设置 enable_clipboard=true 启用，并确保已安装 wl-clipboard。
• QMenu（原生上下文菜单）可能不会显示在 AT-SPI2 中——Qt 的 AT-SPI2 桥接对 Wayland 上的弹出菜单支持不完整。上下文菜单可能无法显示在 accessibility_tree 或 find_ui_elements 中。解决方法：使用 screenshot 目视定位菜单项，然后按坐标点击。
• 屏幕边缘触发器无法与 EIS 输入配合使用——自动隐藏面板和 layer-shell 触发条依赖 Wayland 表面输入路由，而该路由可能无法响应 EIS 注入的指针事件。解决方法：改用 dbus_call 配合 KWin 脚本，或使用键盘快捷键。
• AT-SPI2 坐标转换仅尽力而为——Wayland 客户端报告的是窗口局部坐标（按设计，它们不知道窗口在屏幕上的全局位置）。kwin-mcp 使用每个窗口在合成器端的几何信息（通过 KWin 脚本查询，并按标题匹配）将其转换为真实屏幕坐标。如果无法匹配窗口，坐标将回退为窗口局部坐标——请对照 screenshot 进行确认。

故障排除与调试

详细的 libei/EIS 诊断（KWIN_MCP_DEBUG_EI=1）

设置环境变量 KWIN_MCP_DEBUG_EI=1，即可为 EIS 输入注入路径启用详细诊断（kwin-mcp 直接连接到 KWin 的 libei）：

KWIN_MCP_DEBUG_EI=1 uv run kwin-mcp

启用后，kwin_mcp.input 日志记录器会提升至 DEBUG 级别，并配置 stderr 处理器，记录 EIS 设备生命周期事件 （ADDED / REMOVED / RESUMED / PAUSED / SEAT_REMOVED）、设备停滞和连接重建情况。当输入注入无声无息地不起作用或行为异常时，可使用此功能：日志会显示 KWin 是否在输入操作期间暂停或移除其 EIS 设备，以及 kwin-mcp 是否成功重建连接。

KWIN_MCP_DEBUG_EI=1 uv run kwin-mcp 2>eis-debug.log

其他症状

• session_start 输出中显示 No input backend available——KWin 未公开其 EIS RemoteDesktop 接口；会话会降级为仅支持截图和 AT-SPI2 的会话（无法注入输入）。请检查 KWin 版本（需要 Plasma 6）以及服务日志中的降级原因。
• keyboard_type_unicode 在虚拟会话中失败——kwin_wayland --virtual 不会公开 wtype 所需的虚拟键盘协议；剪贴板回退方案（需要 wl-clipboard）是此类环境中的主要路径。

贡献

欢迎贡献！有关开发环境设置、代码风格指南和拉取请求流程，请参阅 CONTRIBUTING.md。

git clone https://github.com/VibeProgramm/kwin-mcp.git
cd kwin-mcp
uv sync
uv run ruff check src/
uv run ruff format --check src/
uv run ty check src/

许可证

MIT