Arch Linux / CachyOS & Niri DE MCP Server (arch-niri-mcp)

An enterprise-grade Model Context Protocol (MCP) server that enables AI assistants (Antigravity, Claude Desktop, Cursor, VS Code, Windsurf, Zed) to seamlessly inspect, control, and automate Arch Linux, CachyOS, and the Niri Desktop Environment (scrollable tiling Wayland compositor).

---

🌟 Key Features

• 🔍 Automatic CLI Discovery: Dynamically scans system PATH and categorizes installed package managers, terminals, Wayland helpers, and desktop tools.
• 🖥️ Niri DE Window & Layout Control: Query windows, workspaces, monitors, layer-shell surfaces, floating states, layout columns, tabbed modes, and focus states via live JSON IPC.
• 💻 Native Terminal Execution: Execute terminal commands in user's default shell (fish, zsh, bash), or spawn interactive graphical terminal windows (Alacritty, Kitty, Foot, Ghostty).
• ⚙️ System & Hardware Management: Systemd services (systemctl), PipeWire audio (wpctl), screen brightness (brightnessctl), Wayland clipboard (wl-clipboard), notifications (notify-send), network connections (nmcli), battery stats, and hardware summary (fastfetch).
• 📦 Package Management: Query pacman packages and search Arch User Repository (AUR) & CachyOS repos via yay.

---

🧰 Complete Tools Reference (35 Tools)

🔍 1. Auto-Discovery & Terminal Suite (5 Tools)

Tool	Description
arch_discover_tools	Dynamically scans system PATH and returns an inventory of installed CLI tools, package managers, terminals, and desktop helpers.
arch_get_shell_info	Inspects user default shell ($SHELL), PATH directories, $WAYLAND_DISPLAY, and detected terminal emulator.
arch_exec_terminal_cmd	Safely executes terminal/CLI commands in the user's shell environment with stdout/stderr capture, working directory, and timeout control.
arch_spawn_terminal	Launches an interactive graphical terminal window (Alacritty, Kitty, Foot, Ghostty) inside Niri DE session.
arch_journalctl	Fetches systemd service or kernel logs via journalctl.

🖥️ 2. Niri Desktop Environment Suite (16 Tools)

Tool	Description
niri_get_windows	Lists open windows with app IDs, titles, window IDs, workspace IDs, and focus state.
niri_get_workspaces	Lists workspaces, index, names, output monitors, and active status.
niri_get_outputs	Lists connected display monitors, resolutions, scale, and focus state.
niri_get_layers	Lists active Wayland layer-shell surfaces (desktop bars, panels, notifications, quickshell).
niri_get_keyboard_layouts	Lists configured keyboard layouts and active layout index.
niri_get_focused	Inspects currently focused window and display monitor.
niri_focus_window	Switches focus to a window by numeric ID or title/app_id search string.
niri_focus_workspace	Switches active workspace by index or name.
niri_move_window_to_workspace	Moves focused window/column to target workspace by index or name.
niri_move_window_direction	Moves window/column (left, right, up, down, first, last).
niri_set_column_width	Adjusts column width (50%, 33%, +10%, expand, switch-preset).
niri_close_window	Closes focused window or target window by ID.
niri_reload_config	Reloads Niri configuration file (config.kdl).
niri_perform_action	Executes any Niri layout action (maximize-column, toggle-window-floating, center-column, toggle-overview, toggle-column-tabbed-display, etc.).
niri_spawn_app	Launches applications inside the Niri compositor session.
niri_take_screenshot	Captures full screen or focused window screenshot.

🐧 3. Arch Linux & CachyOS System Suite (14 Tools)

Tool	Description
arch_get_system_info	Retrieves hardware overview, OS version, kernel, CPU, GPU, memory, and uptime via fastfetch.
arch_package_query	Searches pacman package database (pacman -Qs / pacman -Ss).
arch_aur_search	Searches Arch User Repository (AUR) & CachyOS repos via yay -Ss.
arch_check_updates	Lists pending system package updates (checkupdates / pacman -Qu).
arch_systemctl	Views status or controls systemd user/system units (start, stop, restart, enable, disable).
arch_process_list	Lists processes ordered by CPU/Memory or searches by name.
arch_kill_process	Terminates process by PID.
arch_audio_control	Queries audio status, adjusts volume percentage (%), or toggles mute via PipeWire (wpctl).
arch_brightness_control	Queries or sets screen brightness percentage (brightnessctl).
arch_send_notification	Sends desktop notifications to Niri DE via notify-send with custom icons & urgency levels.
arch_network_status	Queries active Wi-Fi, Ethernet, and network devices via nmcli.
arch_battery_status	Queries laptop battery charge level, status, and power draw.
arch_clipboard_get	Reads Wayland clipboard text (wl-paste).
arch_clipboard_set	Sets Wayland clipboard text (wl-copy).

---

📦 Installation

Option 1: Automated Script

git clone https://github.com/oki3505F/arch-niri-mcp.git
cd arch-niri-mcp
./install.sh

Option 2: Using uv (Recommended)

git clone https://github.com/oki3505F/arch-niri-mcp.git
cd arch-niri-mcp
uv venv .venv
source .venv/bin/activate
uv pip install -e .

---

⚙️ AI Client Configuration

1. Claude Desktop (claude_desktop_config.json)

Add the following to your ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "arch-niri-control": {
      "command": "/path/to/arch-niri-mcp/.venv/bin/arch-niri-mcp",
      "args": []
    }
  }
}

2. Antigravity / Cursor / VS Code / Windsurf (.mcp.json)

Add to your project .mcp.json or client MCP settings:

{
  "mcpServers": {
    "arch-niri-control": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/arch-niri-mcp",
        "arch-niri-mcp"
      ]
    }
  }
}

---

🧪 Testing & Verification

Run the server executable directly via stdio:

/path/to/arch-niri-mcp/.venv/bin/arch-niri-mcp

Or verify registered tools in Python:

source .venv/bin/activate
python3 -c "import arch_niri_mcp.server as s; print('Registered tools:', len(s.mcp._tool_manager._tools))"

---

🏷️ GitHub Topics & Keywords

arch-linux • cachyos • niri • niri-de • wayland • mcp • mcp-server • model-context-protocol • desktop-automation • window-management • pipewire • claude-desktop • cursor • antigravity

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.