omarchy-mcp

让任何兼容 MCP 的 LLM 完全掌控 Omarchy Linux 桌面。

omarchy-mcp 将 AI 编码代理转变为真正的桌面操作者。通过一个 MCP 服务器，代理可以管理主题和外观、启动应用、截屏和录屏、控制音频和网络、读取系统状态、驱动 Hyprland 窗口和平铺布局，以及编排整个多代理工作区——共 15 个模块、108 个工具。

该项目围绕一条规则构建：桌面变更并非仅仅因为命令执行了就代表成功。 每个操作都会对照测量到的桌面状态进行确认——几何信息、焦点、服务状态——这样代理就能自主行动而不会静默失败。

状态

有关逐工具的验证状态，请参阅 COMMANDS.md；有关计划中的里程碑，请参阅 ROADMAP.md。

Related MCP server: linux-computer-use

为什么存在

桌面控制工具通常只报告操作已派发，却不检查是否生效。这对于平铺窗口管理器尤其不可靠，因为焦点、浮动规则、全屏状态、工作区规则和鼠标都可能改变目标。

该服务器补上了缺失的反馈回路：

• 窗口变更会报告测量到的前后状态和明确的判定结果。

• 显式的地址和匹配选择器可减少与焦点相关的错误。

• PID 祖先链保护可防止代理关闭自己的宿主窗口。

• 破坏性系统操作需要显式配置选择加入。

• health_check 可诊断缺失的命令、布局安装和桌面连接性。

• agent_grid 将整个多代理工作区请求转化为一个经过验证的 MCP 操作。

快速开始

要求

• 已安装的 Omarchy 桌面

• 带 Omarchy Lua 配置桥接的 Hyprland

• Node.js 20 或更高版本

• npm

个别功能还可能使用 wtype、nmcli、bluetoothctl、wpctl、grim 和 wl-copy。health_check 会报告哪些可选命令可用。

构建

git clone https://github.com/hlsitechio/Omarchy-MCP.git
cd Omarchy-MCP
npm ci
npm run build
npm test

MCP 入口点是：

node /absolute/path/to/Omarchy-MCP/build/index.js

安装原生网格布局

常规桌面工具可以在没有自定义布局的情况下运行，但确定性的网格/主从平铺和 agent_grid 需要它。

install -Dm644 hypr/layouts.lua ~/.config/hypr/layouts.lua

确保用户 Hyprland 配置加载它：

require("hypr.layouts")

然后重新加载并检查配置：

hyprctl reload
hyprctl configerrors

/usr/share/omarchy 下的 Omarchy 包文件应保持不动；布局应放在 ~/.config/hypr 下的用户配置中。

连接 MCP 客户端

任何支持本地 stdio MCP 服务器的客户端都可以启动 build/index.js。

OpenCode

将此添加到 ~/.config/opencode/opencode.json，将路径替换为仓库的绝对路径：

{
  "mcp": {
    "omarchy": {
      "type": "local",
      "command": [
        "node",
        "/absolute/path/to/Omarchy-MCP/build/index.js"
      ],
      "enabled": true
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "omarchy": {
      "command": "node",
      "args": ["/absolute/path/to/Omarchy-MCP/build/index.js"]
    }
  }
}

重新构建后重启或重新连接现有的 MCP 客户端，以便重新加载工具模式。

可以尝试的首批提示

• “检查我的 Omarchy MCP 是否健康。”

• “显示每个窗口及其工作区和几何信息。”

• “在下一个空工作区打开一个 2x2 的 OpenCode 网格。”

• “把 Claude 放在右上角，Codex 放在右下角。”

• “把 Firefox 移到工作区 4，并确认它最终到了哪里。”

• “把这个窗口吸附到左上角，告诉我它的最终尺寸。”

• “列出附近的 Wi-Fi 网络，但不要连接任何网络。”

一条命令创建编码代理工作区

agent_grid 启动独立的 Omarchy TUI 窗口，应用原生网格布局，分配精确或稀疏的单元格，并验证每个窗口的应用类、工作区、浮动状态和观测到的几何信息。

对于四个应用，请请求一个 2x2 网格。字面上的 4x4 网格包含 16 个单元格，完全填充时会启动 16 个应用。

同质网格

提示：

在此仓库中打开一个 2x2 的 OpenCode 网格。

等效参数：

{
  "agent": "opencode",
  "cols": 2,
  "rows": 2,
  "workspace": "next_empty",
  "cwd": "/path/to/project"
}

混合稀疏网格

提示：

在右上角打开 Claude，在右下角打开 Codex。

等效参数：

{
  "cols": 2,
  "rows": 2,
  "placements": [
    { "agent": "claude", "position": "top_right" },
    { "agent": "codex", "position": "bottom_right" }
  ]
}

支持的代理有 OpenCode、Claude、Codex、Gemini、Copilot、Crush、Grok、Oh My Pi（omp）和 Pi。使用 dry_run: true 可以在不打开窗口的情况下验证完整计划。

命名的角落分配和显式的行/列分配在用户切换工作区后仍然保留。启动前会统计已有的平铺窗口，如果请求超过网格容量则会被拒绝。

工具分组

完整列表及其实时测试状态维护在 COMMANDS.md 中。

安全模型

无 shell 插值

命令通过 Node 的 execFile 或 spawn 以参数数组方式执行；用户输入不会拼接进 shell 命令。

破坏性操作需选择加入

关机、重启、软件包安装、系统更新和配置刷新默认禁用。通过以下方式启用：

mkdir -p ~/.config/omarchy-mcp
printf '%s\n' '{"enableDangerous": true}' > ~/.config/omarchy-mcp/config.json

或设置进程级覆盖：

OMARCHY_MCP_ENABLE_DANGEROUS=1 node build/index.js

仅对您信任的客户端和会话使用此设置。

宿主窗口保护

关闭窗口和其他高风险操作会解析 MCP 宿主进程的 PID 祖先链，并拒绝以自身的终端窗口为目标。变更操作优先使用显式窗口地址，因为 Hyprland 焦点可能跟随鼠标。

验证结果

窗口变更工具会返回诸如 confirmed、split_confirmed、opened_but_not_split 或 not_detected 等状态，同时附带测量到的状态和适当的恢复提示。

架构

MCP client
    │  JSON-RPC over stdio
    ▼
MCP tool + Zod input validation
    │
    ├── Omarchy CLI ───────────── themes, capture, power, applications
    ├── Hyprland Lua dispatcher ─ windows, workspaces, native layout
    └── System CLIs ───────────── nmcli, bluetoothctl, wpctl, upower
    │
    ▼
State reread + geometry/verdict engine
    │
    ▼
Structured MCP result with STATUS, evidence, and HINT

源码布局：

src/index.ts              server and tool registration
src/exec.ts               shell-free process execution
src/hypr.ts               desktop introspection and verification helpers
src/result.ts             consistent MCP success/error results
src/config.ts             safety configuration
src/tools/                 tool domains
hypr/layouts.lua          native deterministic grid/master layout
test/                      automated and manual live tests

Hyprland 窗口派发使用 Omarchy Lua API，例如：

hl.dsp.window.resize({ window = "address:0x...", x = 900, y = 700, relative = false })

原生布局支持 grid 和 master 模式，以及用于强制尺寸、排序、交换、稀疏单元格和每工作区状态的运行时消息。

开发和验证

npm run build      # TypeScript compilation
npm test           # compilation + deterministic planner tests
npm run smoke      # live local MCP/Omarchy smoke test

冒烟测试特意具备桌面感知能力。它检查工具注册、健康报告、只读的 Omarchy/Hyprland 访问、破坏性操作门控和 agent_grid 干运行。视觉变更在真实的 Omarchy 会话上手动验证，并记录在 COMMANDS.md 中。

要进行实时代理网格演练：

node test/live-agent-grid.mjs

此命令会打开真实窗口并更改活动工作区；它不属于 npm test 的一部分。

故障排除

新工具没有出现

运行 npm run build，然后重启或重新连接 MCP 客户端。MCP 客户端通常会在服务器进程的生命周期内缓存工具列表。

health_check 显示网格布局未完全安装

确认 ~/.config/hypr/layouts.lua 存在，用户 Hyprland 配置包含 require("hypr.layouts")，并且 hyprctl configerrors 为空。

窗口命令选择了错误的目标

先调用 window_list，然后使用返回的地址重试，而不是依赖聚焦窗口。这样可以避免 input:follow_mouse 焦点变化。

危险工具显示已禁用

这是安全的默认设置。在审阅安全模型之后才显式启用它。

布局命令报告 Hyprland 警告

某些合成器空操作是预期的——例如，交换全屏窗口或向空单元格交换。MCP 结果会将这些警告与已确认的变更区分开来。

贡献

欢迎在实现、实时验证、文档、测试、可访问性和发布工程方面做出贡献。该仓库为 bug、工具提案和验证报告提供了结构化的问题表单，以及一个与项目安全模型对齐的拉取请求检查清单。

从 CONTRIBUTING.md 开始，然后从 ROADMAP.md 中选择一个贡献方向。广泛或高风险的更改应从 issue 开始，以便在编码前就范围、证据和恢复行为达成一致。

项目文档

• COMMANDS.md — 实现和实时验证台账

• ROADMAP.md — 里程碑、优先级和发布门控

• CONTRIBUTING.md — 贡献和测试工作流

• GOVERNANCE.md — 角色、决策、审查和发布

• SECURITY.md — 私下报告和安全边界

• CODE_OF_CONDUCT.md — 社区参与标准

• AGENTS.md — 供在仓库上工作的编码代理使用的技术上下文

许可证

MIT