Linux Desktop MCP Server

Linux桌面MCP服务器

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

建于 克劳德代码 -整个MCP服务器是使用Anthropic的人工智能编码助手Claude Code开发的。我们很自豪能够展示人工智能辅助开发的可能性！

一个MCP服务器，使用AT-SPI2（辅助技术服务提供商接口）为本地Linux桌面应用程序提供Chrome扩展级语义元素。

特性

• 语义元素引用：就像Chrome扩展程序一样 ref_1, ref_2 系统
• 角色检测：标识按钮、文本字段、链接、菜单等。
• 状态检测：跟踪聚焦、启用、选中、可编辑状态
• 自然语言搜索：按描述查找元素（“保存按钮”、“搜索字段”）
• 跨平台输入：适用于X11、Wayland和XWayland
• GTK/Qt/Electron支持：适用于任何公开可访问性的应用程序

安装

系统相关性

# Ubuntu/Debian
sudo apt install python3-pyatspi gir1.2-atspi-2.0 at-spi2-core

# For X11 input simulation
sudo apt install xdotool

# For Wayland input simulation (recommended)
# Install ydotool from source or your package manager
# Then start the daemon:
sudo ydotoold &

Python包

# From PyPI
pip install linux-desktop-mcp

# Or from source
git clone https://github.com/BeckhamLabsLLC/linux-desktop-mcp.git
cd linux-desktop-mcp
pip install -e .

启用辅助功能

确保在桌面环境中启用了可访问性：

• GNOME：设置→ 无障碍→ 启用辅助功能
• KDE：系统设置→ 无障碍
• 大多数现代台式机默认启用了此功能

配置

增添 ~/.claude/settings.json:

{
  "mcpServers": {
    "linux-desktop": {
      "command": "linux-desktop-mcp"
    }
  }
}

或者，如果从源代码安装：

{
  "mcpServers": {
    "linux-desktop": {
      "command": "python",
      "args": ["-m", "linux_desktop_mcp"]
    }
  }
}

可用工具

desktop_snapshot

使用语义元素引用捕获可访问性树。

Parameters:
  app_name: str (optional) - Filter to specific application
  max_depth: int (default: 15) - Tree traversal depth

Returns:
  Tree of elements with ref_ids:
  - ref_1: [application] Firefox
    - ref_2: [frame] "GitHub - Mozilla Firefox"
      - ref_3: [button] "Back" (clickable)
      - ref_4: [entry] "Search or enter address" (editable, focused)

desktop_find

通过自然语言查询查找元素。

Parameters:
  query: str - "save button", "search field", "menu containing File"
  app_name: str (optional)

Returns:
  Matching elements with refs, states, and actions

desktop_click

按参照或坐标单击图元。

Parameters:
  ref: str - Element reference (e.g., "ref_5")
  element: str - Human description for logging
  coordinate: [x, y] - Fallback if no ref
  button: left|right|middle
  click_type: single|double
  modifiers: [ctrl, shift, alt, super]

desktop_type

在元素中键入文本。

Parameters:
  text: str - Text to type
  ref: str - Element to focus first (optional)
  element: str - Human description
  clear_first: bool - Ctrl+A, Delete before typing
  submit: bool - Press Enter after

desktop_key

按键盘键/快捷键。

Parameters:
  key: str - Key name (Return, Tab, Escape, a, etc.)
  modifiers: [ctrl, shift, alt, super]

desktop_capabilities

检查可用的自动化功能。

示例用法

示例1：在Firefox中导航到网站

User: "Open GitHub in Firefox"

Claude uses:
1. desktop_snapshot(app_name="Firefox")
   → Returns UI tree with elements like:
     - ref_5: [entry] "Search or enter address" (editable, focused)
     - ref_12: [button] "Go" (clickable)

2. desktop_click(ref="ref_5", element="URL bar")
   → Clicks to focus the address bar

3. desktop_type(text="https://github.com", ref="ref_5", clear_first=True, submit=True)
   → Types the URL and presses Enter

Result: Firefox navigates to GitHub

示例2：在LibreOffice中保存文件

User: "Save this document as 'report.odt'"

Claude uses:
1. desktop_key(key="s", modifiers=["ctrl"])
   → Opens the Save dialog

2. desktop_snapshot(app_name="LibreOffice")
   → Returns dialog elements including:
     - ref_8: [entry] "File name:" (editable)
     - ref_15: [button] "Save" (clickable)

3. desktop_type(text="report.odt", ref="ref_8", clear_first=True)
   → Types the filename

4. desktop_click(ref="ref_15", element="Save button")
   → Clicks Save

Result: Document saved as report.odt

示例3：在代码编辑器中搜索

User: "Search for 'TODO' comments in VS Code"

Claude uses:
1. desktop_find(query="search", app_name="Code")
   → Finds search-related elements

2. desktop_key(key="f", modifiers=["ctrl", "shift"])
   → Opens global search panel

3. desktop_snapshot(app_name="Code")
   → Returns search panel elements:
     - ref_22: [entry] "Search" (editable, focused)
     - ref_25: [checkbox] "Match Case"

4. desktop_type(text="TODO", ref="ref_22", submit=True)
   → Types search query and executes search

Result: VS Code shows all TODO comments across the project

示例4：多窗口自动化的窗口定位

User: "Help me copy data from the spreadsheet to the email"

Claude uses:
1. desktop_context(list_available=True)
   → Lists all available windows

2. desktop_target_window(app_name="LibreOffice Calc", color="green")
   → Targets spreadsheet with green border

3. desktop_target_window(app_name="Thunderbird", color="blue")
   → Targets email client with blue border

4. desktop_snapshot()
   → Only shows elements from targeted windows (reduced context)

5. [Proceeds with copy/paste operations between windows]

Result: Claude can efficiently work across multiple applications

平台支持

故障排除

“AT-SPI2不可用”

sudo apt install python3-pyatspi gir1.2-atspi-2.0 at-spi2-core

“AT-SPI2注册表未运行”

确保在桌面设置中启用了可访问性。您可能需要注销并重新登录。

“没有可用的输入后端”（Wayland）

# Install and start ydotool daemon
sudo ydotoold &

元素未显示

某些应用程序可能不会公开可访问性信息。现代的GTK3/4、Qt5/6和Electron应用程序通常运行良好。

建筑

┌─────────────────────────────────────────────────────────────┐
│                     MCP Protocol Layer                       │
│              (JSON-RPC over stdio, tool defs)                │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                  Reference Manager                           │
│          (ref_1, ref_2 mapping, lifecycle, GC)              │
└─────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┴───────────────────┐
          │                                       │
┌─────────────────────┐             ┌─────────────────────────┐
│   AT-SPI2 Backend   │             │   Input Backends        │
│     (pyatspi)       │             │ (ydotool/xdotool/wtype) │
└─────────────────────┘             └─────────────────────────┘

贡献

这个项目是用Claude Code创建的，我们热烈欢迎您的贡献！您是否愿意：

• 报告错误或请求功能
• 提交拉取请求
• 分叉并构建自己的版本
• 改进文档

我们非常愿意提供帮助和合作。看 贡献.md 作为指导方针。

隐私政策

看 隐私政策.md 了解我们的完整隐私政策。简而言之：Linux Desktop MCP完全在您的本地计算机上运行，不收集任何数据，也不需要网络连接。

许可证

麻省理工学院-参见 许可证 了解详情。