omni-notify-mcp · Setup help

1 Install — already done if you can read this

If you opened this page, the server is already running on http://localhost:3737. To start it again later:

npx omni-notify-mcp

No install needed — npx fetches and runs it on demand. To pin a version: npx omni-notify-mcp@latest.

2 Register with your AI client

Pick your tool. The config is the same shape everywhere — only the file path changes.

Easiest: one CLI command, no file editing needed.

claude mcp add notify -- npx -y omni-notify-mcp

Or edit ~/.claude.json directly:

{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "omni-notify-mcp"]
    }
  }
}

Restart Claude Code. Verify with /mcp — you should see the notify server listed.

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project (workspace-scoped):

{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "omni-notify-mcp"]
    }
  }
}

Open Cursor Settings → MCP to verify the server shows up green.

VS Code 1.86+ has native MCP support — no extension needed. Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "notify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "omni-notify-mcp"]
    }
  }
}

Or via Command Palette → MCP: Add Server → npm package → omni-notify-mcp.

Edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "omni-notify-mcp"]
    }
  }
}

Fully quit Claude Desktop and reopen. The 🔌 icon should show notify connected.

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "notify": {
      "command": "npx",
      "args": ["-y", "omni-notify-mcp"]
    }
  }
}

Edit ~/.config/zed/settings.json — add under context_servers:

{
  "context_servers": {
    "notify": {
      "command": {
        "path": "npx",
        "args": ["-y", "omni-notify-mcp"]
      }
    }
  }
}

Any MCP-compatible client just needs to spawn omni-notify-mcp over stdio:

npx -y omni-notify-mcp

Or for HTTP/SSE-based clients, point them at the running UI server's MCP endpoint:

http://localhost:3737/mcp

Add ?tag=<name> to the URL to give the session a routing tag (e.g. ?tag=alphawave — see multi-session docs).

3 Configure your channels

Decide where notifications should land — desktop, Telegram, SMS, email — and tune Do Not Disturb / idle gating.

→ Open settings

What the AI gets

Six tools, all server-configured. The agent never names a channel — it just calls notify/ask and your settings decide where it goes:

`notify`	Send a message. `priority=low\|normal\|high` controls fan-out and bypasses DND when high.
`ask`	Send a question and wait for your reply (Telegram or email link).
`poll`	Drain unsolicited messages you sent the agent.
`get_idle_seconds`	Seconds since your last keyboard/mouse input.
`get_idle_config`	The server's idle-gating policy.
`get_dnd_status`	Whether Do Not Disturb is currently suppressing.

Well-behaved agents pre-flight with get_idle_seconds and skip the notif entirely if you're at the keyboard. The MCP instructions field tells every connecting client this — no per-prompt prodding required.

Troubleshooting

Agent says "tool not found" for notify

Restart your AI client after editing the config file. Most clients only read MCP config at startup.

Notification didn't arrive

Check the activity log on the main page — it shows every send attempt and any error. Common causes: channel disabled, Do Not Disturb active, or idle-gating skipped because you were typing.

Telegram bot isn't replying

Make sure you've messaged your bot at least once (so it has a chat ID). Click Detect on the Telegram card to auto-fill it.

Where's my config stored?

~/.notify-mcp/config.json. Secrets are masked when read back via the API but stored plain on disk — same as ~/.claude.json.