Ohai

MCP for Quickshell based graphical notifications on Linux.

qml

0

GitHub Stars

qml

Language

4 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "khughitt-ohai": {
      "command": "node",
      "args": [
        "/path/to/ohai-mcp/bin/ohai-mcp"
      ],
      "env": {
        "OHAI_TRANSITION": "glow",
        "OHAI_DEFAULT_IMAGE": "claude"
      }
    }
  }
}

You can run the ohai-mcp server to display notification popups via Quickshell on Linux. It provides a programmable MCP interface to trigger and control popups from clients, with predefined images, patterns, and transition effects for rich, interactive alerts.

How to use

You use this MCP server by starting it as a local, stdio MCP target and configuring clients to talk to it. Clients can request popups with a title, body, severity, and visuals, then Quickshell renders those notifications on screen. You can customize default visuals through environment variables and per-client settings, and you can test behavior with the included helpers and presets.

How to install

Prerequisites: ensure you have Linux and Node.js 18 or newer installed on your system.

Install dependencies for the project and prepare the build.

npm install
npm run build

Configuration and usage notes

The server exposes a stdio MCP endpoint that you run with a basic Node command, pointing to the built MCP binary. You can configure multiple MCP clients by creating separate runtime configurations, each using the same binary but with different environment defaults.

Environment defaults control the visuals for notifications, such as the default image and the transition effect.

Environment variables

Two environment variables are commonly used to tailor the default visuals and behavior for all clients.

Development

If you want to contribute, you can run the development workflow to lint, format, test, and build the project.

Troubleshooting and testing tips

Use the provided CLI helper to test how notifications appear. Verify that the IPC target is registered in Quickshell and that you can trigger notifications with the test presets.

Available tools

ohai

Display a notification popup with customizable title, body, severity, color, timeout, background pattern, image, workspace, app focus, and entry transition.

ohai_status

Check if Quickshell is running with the ohai IPC target registered.

ohai_test

CLI helper to test notification appearances using presets and custom options.