Polybar Notification MCP

ohai-mcp

An MCP server that displays notification popups via Quickshell on Linux.

Installation

npm install
npm run build

Tools

ohai

Display a notification popup.

ohai_status

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

Transition Effects

Set a default transition via environment variable:

export OHAI_TRANSITION=ghost

Quickshell Setup

1. Start the popup daemon:

qs -p /path/to/ohai-mcp/ohai/shell.qml

2. Verify the IPC target is registered:

qs ipc show
# Should list: target ohai

3. Test manually:

qs ipc call ohai notify "Hello" "Test message" "info" 5 "" "" "" "" "" "glow"

4. Controls while popup is visible:
   • Escape - hide popup
   • Backtick (`) - switch to workspace or focus app (if configured), then hide

Testing with ohai-test

A CLI helper for testing notification appearance:

bin/ohai-test [preset]           # Run a preset
bin/ohai-test custom [options]   # Custom notification

Presets:

Custom options:

bin/ohai-test custom \
  -t "Title" \
  -b "Body text" \
  -s warn \
  -i claude \
  -p grid-01 \
  -d 10 \
  -c "#ff00ff" \
  -x ghost

Bundled Assets

Patterns (background overlays):

• waves-01, grid-01, stripes-01, sunset-01

Images (left panel):

• ghost (default), claude, openai

Use an absolute path for custom assets.

Integration

Use environment variables to configure defaults per client.

Claude Code

~/.claude.json:

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

Cursor

Add to MCP settings:

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

codex-cli

~/.codex/config.toml:

[mcp_servers.ohai]
command = "node"
args = ["/path/to/ohai-mcp/bin/ohai-mcp"]

[mcp_servers.ohai.env]
OHAI_DEFAULT_IMAGE = "openai"
OHAI_TRANSITION = "glow"

Auto-launch (Hyprland)

exec-once = qs -p /path/to/ohai-mcp/ohai/shell.qml

Environment Variables

Architecture

┌─────────────┐     qs ipc call      ┌─────────────────┐
│  MCP Client │ ──────────────────▶  │   Quickshell    │
│  (Claude)   │                      │   (shell.qml)   │
└─────────────┘                      └─────────────────┘
       │                                     │
       │                                     │
       ▼                                     ▼
┌─────────────┐                      ┌─────────────────┐
│  ohai-mcp   │                      │  IpcHandler     │
│  (Node.js)  │                      │  target: "ohai" │
└─────────────┘                      └─────────────────┘

The MCP server communicates with Quickshell via its built-in IPC mechanism (qs ipc call), which uses a Unix socket for instant, reliable delivery.

Development

npm run dev      # Watch mode
npm run build    # Build
npm run lint     # Lint
npm run format   # Format

Requirements

• Linux with Quickshell
• Node.js 18+