Skip to main content
Glama

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

Python 3.10+ License: MIT MCP Protocol Arch Linux CachyOS Niri DE

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.


Related MCP server: omarchy-mcp

๐Ÿงฐ 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.

Available Tools

35 tools
arch_audio_controlA

Control PipeWire audio volume or muting via wpctl on Arch/CachyOS. action: 'status', 'set_volume', 'toggle_mute' value: Volume percentage integer (e.g. 50, 80) when action is 'set_volume'.

Inputs: action (required), value. Returns: result

arch_battery_statusA

Check battery status, capacity level, and charging state.

Inputs: no named parameters. Returns: object

arch_brightness_controlA

Query or adjust screen brightness using brightnessctl. action: 'get' or 'set' percent: Target brightness percentage integer (1-100) when action is 'set'.

Inputs: action, percent. Returns: object

arch_check_updatesA

Check pending software updates available for Arch Linux / CachyOS.

Inputs: no named parameters. Returns: result

arch_clipboard_getA

Get current text content from the Wayland clipboard (wl-paste).

Inputs: no named parameters. Returns: result

arch_clipboard_setA

Set text content into the Wayland clipboard (wl-copy).

Inputs: text (required). Returns: result

arch_discover_toolsB

Automatically discover all installed CLI utilities, terminal emulators, package managers, Wayland helpers, and desktop monitors installed on the system.

Inputs: no named parameters. Returns: object

arch_exec_terminal_cmdA

Execute any terminal/CLI command in the user's shell environment. Captures stdout, stderr, exit code, and handles timeouts cleanly.

Inputs: command (required), cwd, timeout_seconds. Returns: object

arch_get_shell_infoA

Inspect user default shell, PATH environment, active desktop session, and installed terminal emulators.

Inputs: no named parameters. Returns: object

arch_get_system_infoA

Retrieve Arch Linux / CachyOS system hardware overview, OS version, kernel, CPU, GPU, memory, and uptime.

Inputs: no named parameters. Returns: object

arch_journalctlB

Fetch systemd service or kernel logs via journalctl.

Inputs: lines, unit_name, user_mode, errors_only. Returns: result

arch_kill_processA

Terminate a running process by its PID using specified signal (SIGTERM or SIGKILL).

Inputs: pid (required), signal. Returns: result

arch_network_statusA

Query active network connections, Wi-Fi, and Ethernet devices using nmcli.

Inputs: no named parameters. Returns: object

arch_package_queryB

Query Arch Linux / CachyOS pacman package database (search installed packages or remote repositories).

Inputs: query (required), installed_only. Returns: result

arch_process_listA

List running system processes ordered by CPU/Memory usage or search process by name.

Inputs: limit, search_term. Returns: result

arch_send_notificationA

Send a desktop notification to Niri DE via notify-send. urgency: 'low', 'normal', 'critical'

Inputs: summary (required), body, icon, urgency. Returns: result

arch_spawn_terminalB

Launch an interactive graphical terminal window (e.g. Alacritty, Kitty, Foot) inside Niri DE session. Optionally pass a command to run inside the terminal window.

Inputs: command, working_dir. Returns: result

arch_systemctlA

Manage systemd services on Arch / CachyOS. action: 'status', 'start', 'stop', 'restart', 'enable', 'disable', 'is-active' unit_name: Name of systemd unit (e.g., 'pipewire.service', 'bluetooth', 'networkmanager') user_mode: True for user services (--user), False for system-wide services

Inputs: action (required), unit_name (required), user_mode. Returns: result

niri_close_windowA

Close the currently focused window, or close a specific window by its numeric ID.

Inputs: window_id. Returns: result

niri_focus_windowA

Focus a window in Niri. Provide window_id (numeric ID) OR search_query (matches window title or app_id like 'firefox', 'terminal', 'code').

Inputs: window_id, search_query. Returns: result

niri_focus_workspaceA

Switch active workspace in Niri by index number (e.g. '1', '2', '3') or workspace name.

Inputs: workspace_ref (required). Returns: result

niri_get_focusedA

Get detailed information about the currently focused window and currently focused display monitor.

Inputs: no named parameters. Returns: object

niri_get_keyboard_layoutsA

Get configured keyboard layouts and current active layout index in Niri.

Inputs: no named parameters. Returns: object

niri_get_layersA

List open Wayland layer-shell surfaces in Niri (desktop bars, panels, quickshell, notifications).

Inputs: no named parameters. Returns: result

niri_get_outputsA

List connected display monitors (outputs) with resolutions, modes, scaling, and focus state.

Inputs: no named parameters. Returns: result

niri_get_windowsA

List all open windows in Niri DE with titles, app IDs, window IDs, workspace IDs, and focus status.

Inputs: no named parameters. Returns: result

niri_get_workspacesA

List all workspaces in Niri DE with workspace index, names, output monitors, and active status.

Inputs: no named parameters. Returns: result

niri_move_window_directionA

Move focused window or column in specified direction. direction options: 'left', 'right', 'up', 'down', 'first', 'last'

Inputs: direction (required). Returns: result

niri_move_window_to_workspaceA

Move currently focused window/column to specified workspace by index or name.

Inputs: workspace_ref (required). Returns: result

niri_perform_actionC

Perform a Niri layout or window action. Examples of action_name:

  • 'maximize-column': Toggle maximize column width

  • 'toggle-window-floating': Toggle floating window mode

  • 'toggle-overview': Toggle desktop overview

  • 'center-column': Center focused column on screen

  • 'consume-or-expel-window-left': Group/ungroup window

  • 'set-column-width': Set width (e.g. args=['50%'])

  • 'toggle-column-tabbed-display': Switch column between normal and tabbed mode

Inputs: action_name (required), args. Returns: result

niri_reload_configA

Reload Niri DE configuration file (config.kdl).

Inputs: no named parameters. Returns: result

niri_set_column_widthA

Set focused column width. width options: '50%', '33.333%', '+10%', '-10%', 'switch-preset', or 'expand'.

Inputs: width (required). Returns: result

niri_spawn_appA

Launch a desktop application or shell command in the Niri session (e.g., 'kitty', 'firefox', 'thunar', 'pavucontrol').

Inputs: command (required). Returns: result

niri_take_screenshotA

Capture a screenshot on Niri DE. target: 'screen' (entire focused monitor) or 'window' (focused window only). Returns path to saved screenshot image file.

Inputs: target. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.6/5.0

    Scored across 35 tools

    Disambiguation3/5

    While getters are clearly distinct, there is overlap between niri_perform_action and specific tools like niri_set_column_width, and among the three launching tools (niri_spawn_app, arch_spawn_terminal, arch_exec_terminal_cmd) which may confuse agents. However, descriptions clarify their intents.

    Naming Consistency4/5

    Most tools follow a clear prefix_verb_noun pattern (e.g., niri_get_windows, arch_package_query), but a few like arch_systemctl and niri_perform_action break the pattern, and there is stylistic variation (e.g., niri_take_screenshot vs niri_get_*).

    Tool Count3/5

    35 tools is large for a single server, but it serves two distinct domains (Niri DE management and Arch system administration), so each tool has a purpose. Still, it exceeds the typical 15-tool threshold and could be streamlined.

    Completeness5/5

    The server provides thorough coverage of both Niri window manager operations and Arch system administration, including edge features like clipboard, brightness, and AUR search. No major dead ends are apparent.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables querying and controlling the i3 (or Sway) window manager through natural language, offering tools for window management, workspace operations, and session configuration.
      13
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables any LLM to fully control an Omarchy Linux desktop, including themes, apps, screenshots, reminders, audio, brightness, and Hyprland window tiling, with safety guards on destructive operations.
      108
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to automate Hyprland desktop environments through screenshots, mouse/keyboard input, window management, workspaces, clipboard, app launching, and OCR.
      27
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to control Linux desktops and compositors, including Hyprland/Wayland window management, PipeWire audio routing, systemd diagnostics and self-healing, notifications, screenshots, and optional agent memory.
      MIT