arch-niri-mcp
Provides comprehensive Arch Linux system management, including package operations (pacman/AUR search), system updates, systemd unit control, process and hardware monitoring, audio, brightness, network, clipboard, and notifications.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@arch-niri-mcp check for pending package updates"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
PATHand 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 |
| Dynamically scans system |
| Inspects user default shell ( |
| Safely executes terminal/CLI commands in the user's shell environment with stdout/stderr capture, working directory, and timeout control. |
| Launches an interactive graphical terminal window ( |
| Fetches systemd service or kernel logs via |
๐ฅ๏ธ 2. Niri Desktop Environment Suite (16 Tools)
Tool | Description |
| Lists open windows with app IDs, titles, window IDs, workspace IDs, and focus state. |
| Lists workspaces, index, names, output monitors, and active status. |
| Lists connected display monitors, resolutions, scale, and focus state. |
| Lists active Wayland layer-shell surfaces (desktop bars, panels, notifications, quickshell). |
| Lists configured keyboard layouts and active layout index. |
| Inspects currently focused window and display monitor. |
| Switches focus to a window by numeric ID or title/app_id search string. |
| Switches active workspace by index or name. |
| Moves focused window/column to target workspace by index or name. |
| Moves window/column ( |
| Adjusts column width ( |
| Closes focused window or target window by ID. |
| Reloads Niri configuration file ( |
| Executes any Niri layout action ( |
| Launches applications inside the Niri compositor session. |
| Captures full screen or focused window screenshot. |
๐ง 3. Arch Linux & CachyOS System Suite (14 Tools)
Tool | Description |
| Retrieves hardware overview, OS version, kernel, CPU, GPU, memory, and uptime via |
| Searches pacman package database ( |
| Searches Arch User Repository (AUR) & CachyOS repos via |
| Lists pending system package updates ( |
| Views status or controls systemd user/system units ( |
| Lists processes ordered by CPU/Memory or searches by name. |
| Terminates process by PID. |
| Queries audio status, adjusts volume percentage (%), or toggles mute via PipeWire ( |
| Queries or sets screen brightness percentage ( |
| Sends desktop notifications to Niri DE via |
| Queries active Wi-Fi, Ethernet, and network devices via |
| Queries laptop battery charge level, status, and power draw. |
| Reads Wayland clipboard text ( |
| Sets Wayland clipboard text ( |
๐ฆ Installation
Option 1: Automated Script
git clone https://github.com/oki3505F/arch-niri-mcp.git
cd arch-niri-mcp
./install.shOption 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-mcpOr 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 toolsarch_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_aur_searchA
Search Arch User Repository (AUR) & CachyOS software repositories using yay.
Inputs: query (required). 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
Scored across 35 tools
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.
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_*).
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.
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
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables querying and controlling the i3 (or Sway) window manager through natural language, offering tools for window management, workspace operations, and session configuration.13MIT
- AlicenseBqualityBmaintenanceEnables 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.1081MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to automate Hyprland desktop environments through screenshots, mouse/keyboard input, window management, workspaces, clipboard, app launching, and OCR.271MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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