Hyperland-MCP
用于Hyprland桌面自动化的MCP服务器。让AI助手能够看到屏幕、控制鼠标和键盘、管理窗口以及与桌面交互——所有这些都是通过Hyprland的原生Wayland工具实现的。
专为 克劳德代码，但适用于任何MCP客户端。
它做什么
- 截图 --捕获整个桌面、特定显示器、窗口或区域。图像会自动调整大小并进行JPEG压缩，以适应MCP输出限制。每个屏幕截图都包含一个坐标映射，因此AI知道如何将图像位置转换为屏幕坐标。
- 光学字符识别 --使用Tesseract在屏幕上查找并单击文本。
click_text("Send")捕获屏幕截图、运行OCR、查找文本并单击它——所有这些都在一个工具调用中完成。自动将范围调整到活动窗口，以获得更好的准确性。 - 老鼠 --移动、单击、滚动和拖动。定位使用Hyprland的本地
movecursor（像素精确，无鼠标加速问题）。 - 键盘 --键入文本或发送组合键。快捷方式可以针对特定窗口，而无需对其进行聚焦。
- 窗口管理 --列出、聚焦、关闭、移动、调整大小、全屏和浮动窗口。
- 工作区和监视器 --列出工作区，在它们之间切换，查询监视器布局和光标位置。
- 剪贴板 --读写剪贴板文本。
- 应用程序启动 --通过Hyprland启动应用程序（分离式，无外壳扩展）。
需求
- Hyprland （地面合成器）
- Python 3.10+
- 系统工具：
grim,wtype,ydotool,wl-clipboard,tesseract
安装脚本会检查所有这些内容，并提供安装任何缺失的内容。
安装
curl -sSL https://raw.githubusercontent.com/alderban107/hyprland-mcp/main/install.sh | bash安装脚本会自动处理所有内容：
- 检测您的包管理器（pacman、apt、dnf、zypper、xbps、emerge、nix）
- 安装任何缺失的系统依赖项
- 通过pipx安装hyprland mcp
- 使用Claude Code注册MCP服务器
安装后重新启动Claude Code。
证实 claude mcp list --你应该看看 hyprland: ✓ Connected.
Manual installation
pipx install git+https://github.com/alderban107/hyprland-mcp.git
claude mcp add --transport stdio --scope user hyprland -- hyprland-mcp或者从本地克隆：
git clone https://github.com/alderban107/hyprland-mcp.git
cd hyprland-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
claude mcp add --transport stdio --scope user hyprland -- /path/to/hyprland-mcp/.venv/bin/hyprland-mcp工具（27）
屏幕截图和OCR
| 工具 | 说明 |
|---|---|
screenshot | 捕获桌面、显示器、窗口或区域。返回内联JPEG+坐标映射，用于将图像位置转换为屏幕坐标。 |
screenshot_with_ocr | 一次通话中的截图+OCR。返回图像和所有检测到的文本。自动调整活动窗口的范围。 |
click_text | 通过OCR在屏幕上查找文本并单击它。一个工具调用将替换屏幕截图→ 解析→ 点击。自动调整活动窗口的范围。 |
find_text_on_screen | 通过OCR在屏幕上查找文本。返回所有比赛的屏幕坐标，准备就绪 mouse_click. |
type_into | 通过占位符文本查找文本输入字段，单击它，键入，然后按Enter键（可选）。 |
老鼠
| 工具 | 说明 |
|---|---|
mouse_move | 将光标移动到绝对坐标（通过Hyprland的像素精度） movecursor) |
mouse_click | 点击位置或当前位置（左/右/中，单/双） |
mouse_scroll | 在位置或当前位置向上/向下滚动滚轮 |
mouse_drag | 单击并从一个位置拖动到另一个位置 |
键盘
| 工具 | 说明 |
|---|---|
type_text | 键入文本作为键盘输入（通过 wtype) |
key_press | 按以下组合键 ctrl+c, alt+F4 （通过Hyprland sendshortcut) |
send_shortcut | 发送带有显式修饰符和键的快捷方式，可选择针对特定窗口 |
窗口管理
| 工具 | 说明 |
|---|---|
list_windows | 列出所有窗口，包括类别、标题、大小、位置（可按工作区/监视器筛选） |
get_active_window | 获取当前聚焦窗口的详细信息 |
focus_window | 按类别或标题选择器聚焦窗口 |
close_window | 关闭窗口（WM_Close——应用程序可以显示保存对话框） |
move_window | 将窗口移动到像素位置或工作区 |
resize_window | 将窗口调整为精确的像素尺寸 |
toggle_fullscreen | 切换全屏或最大化模式 |
toggle_floating | 切换浮动模式 |
工作区和监视器
| 工具 | 说明 |
|---|---|
list_monitors | 列出连接的监视器，包括分辨率、位置和刷新率 |
list_workspaces | 列出具有窗口数的活动工作区 |
switch_workspace | 按名称或编号切换到工作区 |
get_cursor_position | 获取绝对布局坐标中的当前光标位置 |
剪贴板和系统
| 工具 | 说明 |
|---|---|
clipboard_read | 读取当前剪贴板文本 |
clipboard_write | 将文本写入剪贴板 |
launch_app | 启动应用程序（分离，通过 hyprctl dispatch exec) |
运作原理
屏幕截图坐标映射
多显示器设置和图像缩放使坐标转换变得棘手。每 screenshot 调用返回图像旁边的坐标映射：
Coordinate mapping: This 941x1030 image covers screen region
starting at absolute (5447, 38), native size 941x1030.
To convert image coordinates to absolute screen coordinates:
screen_x = image_x * 1.00 + 5447
screen_y = image_y * 1.00 + 38这可以防止人工智能直接使用图像像素位置作为屏幕坐标——这是多显示器设置中的一种常见故障模式，在这种设置中，显示器在布局中的位置不同。
OCR和深色主题
Tesseract OCR是为白纸上的黑色文本而设计的。大多数桌面应用程序使用深色主题，这会降低OCR的准确性。hyprland mcp自动检测暗背景屏幕截图，并在运行OCR之前将其反转，从而显著提高了文本检测能力。
默认情况下，OCR工具自动将范围调整到活动窗口（可配置为 scope="full" 整个桌面）。更小的捕获区域=更好的OCR精度=更可靠的坐标映射。
鼠标定位
鼠标移动使用 hyprctl dispatch movecursor --Hyprland的原生IPC命令，将光标设置为精确的像素坐标。没有鼠标加速，没有相对移动，没有坐标漂移。ydotool仅用于点击和滚动事件（不涉及定位）。
屏幕截图大小
屏幕截图会自动缩放以适应MCP输出限制。默认值：最大宽度1024px，JPEG质量60。2560x1440的桌面大小约为80-100KB，足够在对话中进行内联显示。
要阅读精细文本或UI详细信息，请使用 region 以全分辨率捕获较小区域或捕获特定区域的参数 window.
项目结构
hyprland_mcp/
server.py # FastMCP instance, all tool definitions, entry point
hyprctl.py # Async wrappers for hyprctl IPC (query, dispatch, batch)
screenshot.py # grim capture + Pillow resize/compress + coordinate mapping
input.py # Mouse (movecursor + ydotool) and keyboard (wtype + sendshortcut)
clipboard.py # wl-copy / wl-paste wrappers
ocr.py # Tesseract OCR with dark-theme preprocessing
errors.py # Exception hierarchy + tool availability checks安全
close_window发送WM_CLOSE——应用程序可以显示“保存更改？”对话框。没有强制杀伤工具。launch_app经历hyprctl dispatch exec--与MCP工艺分离，没有外壳膨胀。- 没有文件系统访问权限——MCP可以看到屏幕并与之交互，但不能读取或写入文件。
- 缺少的系统工具会产生明确的错误消息，列出要安装的内容。
许可证
麻省理工学院