notify-mcp

Generic push-to-phone notifications for any agent or script. Exposes a send_notification MCP tool (available in every Claude Code session) plus a CLI (notify) for cron jobs, daemons, and other non-agent callers — both backed by one provider-agnostic core.

Why it exists: Claude Code's built-in PushNotification tool suppresses the mobile push whenever the terminal "has focus" or the user typed recently. On a remote setup the terminal always reads as focused, so every push is silently dropped. notify-mcp is an independent path that ignores that gate.

Architecture

caller ─┬─ MCP tool  (Claude agents, any session)  ─┐
        └─ CLI / import  (cron, daemons, scripts)   ─┴─► sendNotification() ──► provider (ntfy | pushover | telegram) ──► phone

• src/notify.ts — provider-agnostic core: defaults, truncation, retries w/ backoff, logging. Never throws.
• src/providers/ — one file per provider behind a common Provider interface.
• src/mcp.ts — stdio MCP server exposing send_notification.
• src/cli.ts — thin CLI wrapper.

For agents (MCP tool)

Tool: send_notification. Registered globally, so every Claude session/project inherits it.

Param	Required	Notes
message	yes	The alert body. Lead with the actionable fact.
title	no	Bold title; defaults to config defaults.title.
priority	no	min | low | default | high | max. high/max can pierce Do-Not-Disturb.
tags	no	Labels / ntfy emoji shortcodes, e.g. ["warning"].
source	no	Caller name; rendered as [source] prefix on the title so the user knows the origin.
click	no	URL to open when the notification is tapped.

When to use it: genuine decision + time-sensitivity — an approval/auth needed, a failure, a long job finished — assuming the user is away. Not routine status updates.

For scripts (CLI)

bun run /Users/doug/dev-local/notify-mcp/src/cli.ts \
  --title "Deploy" --priority high --source "ci" --tags "rocket" \
  "prod deploy finished in 4m12s"

Options: --title/-t, --priority/-p, --tags <a,b,c>, --source/-s, --click/-c, --help/-h. Exit code is 0 on success, nonzero on final failure — safe to use in a pipeline guard (notify "…" || true).

Programmatic use from another Bun/Node project:

import { sendNotification } from "/Users/doug/dev-local/notify-mcp/src/notify.ts";

const result = await sendNotification({ message: "hi", priority: "high" });

Config

Lives at ~/.config/notify-mcp/config.json (chmod 600, outside the repo). Override the path with NOTIFY_MCP_CONFIG. Template: config.example.json.

{
  "provider": "ntfy",
  "defaults": { "title": "Notification", "priority": "default", "maxLength": 512, "retries": 2, "timeoutMs": 5000 },
  "ntfy": { "server": "https://ntfy.sh", "topic": "<long-random-topic>" }
}

Switch providers by changing provider and filling the matching block:

• ntfy — { server, topic }. On public ntfy.sh the topic is the password — keep it long, random, and out of logs/commits.
• pushover — { token, user }. Private by design.
• telegram — { botToken, chatId }.

Logs

Every attempt appends a JSONL line to ~/.config/notify-mcp/notify.log (ts, provider, ok, status, attempts, title, message, error). Log-write failures are swallowed so they can't break a caller.

Setup (one-time, user)

1. Install the ntfy app (iOS/Android) and subscribe to your topic on server https://ntfy.sh.
2. Copy config.example.json → ~/.config/notify-mcp/config.json, set the topic, chmod 600.
3. The MCP server is registered in ~/.claude.json (global). New Claude sessions pick it up; an already-running session must be restarted to see the tool.

Test

bun run typecheck
bun run src/cli.ts --priority high "test push"   # expect: Sent via ntfy (HTTP 200, 1 attempt(s)).