Skip to main content
Glama
oki3505F

arch-niri-mcp

by oki3505F
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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: Linux MCP Server

🧰 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.

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • SentinelX

    Operate your Linux servers from your LLM. Every action runs through an auditable allowlist.

  • Sugra API

    Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.

  • TVWizard

    Control Android TV from any AI. 38 MCP tools: playback, recap, recommend, smart-home, schedules.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/oki3505F/arch-niri-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server