kwin MCP

kwin-mcp

KDE Plasma 6 Wayland上Linux桌面GUI自动化的模型上下文协议服务器

](https://pypi.org/project/kwin-mcp/) ](https://pypi.org/project/kwin-mcp/)   

A. 模型上下文协议（MCP） 服务器，使AI代理（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代理提供了结构化的小部件数据（角色、名称、坐标、状态、可用操作），因此它可以与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代理自主操作桌面应用程序。代理读取可访问性树以理解UI，通过30个MCP工具执行操作，并通过屏幕截图观察结果——为任何Wayland应用程序创建一个完整的反馈循环。

实时桌面协作

连接到您的真实桌面会话，让Claude观察您所看到的内容并与之交互。使用 session_connect 或通过 --default-live-session 将实时模式设置为默认模式。还支持连接到在容器内运行的KWin（例如。 systemd-nspawn)用于隔离的代理桌面。

CI/CD中的无头GUI测试

将Linux桌面GUI测试集成到CI/CD管道中。kwin mcp的虚拟会话不需要X11或物理显示服务器，使其适用于Linux上的GitHub Actions或GitLab CI运行器等无头环境。

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

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

快速开始

需要Wayland上的KDE Plasma 6。看 系统要求 了解详情。

1.安装

# Using uv (recommended)
uv tool install kwin-mcp

# Or using pip
pip install kwin-mcp

2.配置克劳德代码

添加到您的项目 .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 技能，它教代理何时调用哪个工具（会话模式选择、观察→ act → 验证循环、US-QWERTY与Unicode打字、AT-SPI2表面局部坐标和其他平台陷阱）。

克劳德代码 --从市场安装插件：

/plugin marketplace add isac322/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.

克劳德代码

添加到您的项目 .mcp.json:

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

或者，如果全局安装：

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

克劳德桌面版

添加到您的 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-70ms）。

运作原理

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、门户）对主机不可见。
2. 显示器隔离 -- kwin_wayland --virtual 使用虚拟帧缓冲区创建自己的Wayland合成器。主机显示器上没有显示窗口。
3. 输入隔离 --输入事件仅通过KWin的EIS接口注入到隔离的合成器中。主机桌面未收到kwin mcp的任何输入。
4. 主目录隔离 （可选）--何时 isolate_home=true 已设置 session_start，使用隔离的XDG目录创建临时HOME目录(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接口。这将返回a libei 文件描述符，允许低级输入模拟，而不需要XDG RemoteDesktop门户（将显示用户授权对话框）。该连接使用：

• 绝对指针定位 用于基于精确坐标的交互
• evdev密钥 具有完整的美国QWERTY键盘输入映射
• 平滑拖动插值 （10+中间步骤），实现逼真的拖动操作
• EIS触摸模拟 用于多点触控手势（点击、滑动、捏合、多指滑动）

电脑屏幕截图工具

这 screenshot 工具通过KWin捕获 org.kde.KWin.ScreenShot2 D-Bus接口（每帧约30-70ms），带 spectacle CLI作为后备方案。对于具有以下功能的行动工具 screenshot_after_ms 参数，相同的D-Bus接口用于快速突发捕获。从管道中读取原始ARGB像素数据，并使用Pillow将其转换为PNG。

可访问性树

通过PyGObject查询隔离会话中的AT-SPI2可访问性总线(gi.repository.Atspi).这提供了一个结构化的树，其中包含所有UI小部件及其角色（按钮、文本字段、菜单项等）、名称、状态（聚焦、启用、可见等）、屏幕坐标和可用操作（单击、切换等）。

系统要求

可选依赖关系：

安装系统依赖项

Arch Linux / Manjaro

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

Fedora (KDE Spin)

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

openSUSE (KDE)

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

Kubuntu / KDE Neon

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

安装

使用紫外线（推荐）

uv tool install kwin-mcp

使用pip

pip install kwin-mcp

来源

git clone https://github.com/isac322/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 可以在单独的会话中挂起。启用 enable_clipboard=true 在 session_start，并确保 wl-clipboard 已安装。
• QMenu（本地上下文菜单）可能不会出现在AT-SPI2中 --Qt的AT-SPI2桥不完全支持Wayland上的弹出菜单。上下文菜单在中可能不可见 accessibility_tree 或 find_ui_elements.解决方法：使用 screenshot 以视觉方式定位菜单项并按坐标单击。
• 屏幕边缘触发器不适用于EIS输入 --自动隐藏面板和图层外壳触发条依赖于Wayland表面输入路由，这可能不会对EIS注入的指针事件做出响应。解决方法：使用 dbus_call 使用KWin脚本或键盘快捷键。
• AT-SPI2坐标是表面局部坐标，而不是屏幕全局坐标 --Wayland客户不知道他们的全球屏幕位置（按设计）。返回的坐标 find_ui_elements 和 accessibility_tree 是相对于窗口的左上角，而不是虚拟屏幕。对于单窗口场景，这通常是可以的；对于多窗口布局，请结合 screenshot 用于绝对定位。

贡献

欢迎投稿！看 贡献.md 用于开发设置、代码风格指南和pull请求过程。

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

许可证

麻省理工学院