notify-hub

Self-hosted, free, multi-channel notification gateway. POST one message with a token and it fans out -- asynchronously, via a durable queue -- to every channel you've enabled: ntfy, Telegram, Email, Slack, Discord, WhatsApp, or a generic webhook. Built so a Claude Code hook can push you "task started" / "task finished" / "Claude needs you" notifications across every project, without ever blocking Claude.

Why

Claude Code (or any long-running script) leaves you watching a terminal for minutes with no way to know when it's done or needs input. notify-hub is a tiny, 100% free, self-hosted service you run once (docker compose up) that turns "send me a push" into a one-line HTTP call, decoupled from delivery by a Redis-backed queue with retries and per-channel dead-lettering.

Related MCP server: Trello Universal MCP Server

Architecture

client (curl / hook script)
  -> POST /notify (Bearer token)                [Fastify API]
  -> enqueue dispatch job                        [Redis / BullMQ]
  -> dispatch worker resolves channel set
  -> one delivery job per channel                [Redis / BullMQ]
  -> delivery worker sends via the channel's adapter
     (ntfy / telegram / email / slack / discord / whatsapp / webhook)

• API only validates + enqueues; it never sends inline, so a slow/broken channel can't make /notify hang.

• Worker does the actual fan-out and delivery; each channel gets its own job so retries/failures are isolated per channel (one channel down doesn't block the others).

• Channels are pluggable: each one implements the same tiny interface (send(notification)); enabling one is a config toggle + credentials, and adding a brand-new one is a small adapter file (see the generic webhook adapter as the reference example).

Quickstart

git clone https://github.com/richardfcampos/notify-hub.git && cd notify-hub
./scripts/setup-env.sh   # guided setup: prompts for each channel's credentials
                         # (hidden input), generates your gateway token, writes
                         # .env with chmod 600. Or do it by hand:
                         #   cp .env.example .env && $EDITOR .env
docker compose up -d --build
curl http://localhost:8080/health
# => {"status":"ok","redis":true}

Send a notification:

curl -X POST http://localhost:8080/notify \
  -H "Authorization: Bearer <your-token-from-TOKENS>" \
  -H "Content-Type: application/json" \
  -d '{"title":"notify-hub","message":"hello from notify-hub"}'
# => 202 {"jobId":"..."}

POST /notify accepts:

Responses: 202 {jobId} (enqueued) · 400 (invalid body / unknown channel name) · 401 (missing/unknown token) · 503 (queue unreachable, so the caller never hangs).

Configuration

All config is env vars (see .env.example for every key). Key ones:

• PORT -- API listen port (compose maps ${PORT:-8080} on the host).

• TOKENS -- ;-separated name:token:defaultChannel1,defaultChannel2 entries. Example: phone:supersecrettoken:ntfy,telegram;desktop:othertoken:discord.

• CHANNELS_ENABLED -- comma-separated list of channels to activate, e.g. ntfy,telegram,discord. A channel not listed here is never attempted, even if a request asks for it. A listed channel missing its required credentials makes the service refuse to start, naming the channel and the missing key -- so misconfiguration is caught immediately, not as a silent drop later.

Channels

Each row is the env keys a channel needs once it's in CHANNELS_ENABLED.

Adding a brand-new channel: implement the NotificationChannel interface (one send() method) in src/channels/adapters/, export a ChannelRegistryEntry (factory + required env keys), and add one line to src/channels/channel-registry.ts. No other core changes needed.

Claude Code hook

A zero-dependency hook script pushes "start" / "end" / "needs-input" events to notify-hub globally, across every Claude Code project. See clients/claude-code/install.md for the full setup (settings.json snippet + env vars).

MCP server

notify-hub also ships as an MCP (Model Context Protocol) server over stdio, exposing three tools -- send_notification, list_channels, check_gateway_health -- so an agent (Claude Code, Claude Desktop, any MCP client) can push notifications and check the gateway as tool calls instead of hand-rolled HTTP. It's a thin client of the already-running gateway (no direct Redis access). See clients/mcp/install.md for the full setup (claude mcp add command + generic mcpServers JSON config).

Admin panel

A local, dark-themed dashboard for managing everything above without hand- editing .env:

• View every channel (ntfy, Telegram, Email, Slack, Discord, WhatsApp, webhook), toggle it on/off, and edit its credentials -- masked by default, revealed with one click.

• Manage token profiles (TOKENS): add/remove, edit the token, and pick each profile's default channels.

• Save & Apply validates, backs up .env (timestamped), writes the new file, and runs docker compose up -d --no-build api worker -- one click, no terminal.

• Send test per channel posts a real notification and shows the actual delivery outcome (✅ sent, or the real failure reason ❌), not just "enqueued".

• Live gateway status (health, redis, active channels) and a tail of recent worker deliveries.

Comes up automatically as part of the stack -- no extra step:

docker compose up -d
# => http://127.0.0.1:8081

npm run admin still works as a host-side dev alternative (no Docker rebuild needed while iterating on the panel itself):

npm run admin
# => admin panel: http://127.0.0.1:8081

Reachability: in compose the host-side bind defaults to 0.0.0.0 (like the other services on a typical homelab host), so the panel is reachable from your other devices -- e.g. over a Tailscale tailnet as http://<machine>:8081. The panel has no auth and displays secrets, so anyone who can reach the port can read and rewrite your config: keep that surface to networks you trust (a WireGuard/Tailscale tailnet is a good fit; an untrusted LAN is not). Set ADMIN_BIND=127.0.0.1 in .env to make it localhost-only. The explicit bind template is asserted by src/admin/compose-invariants.test.ts. The host-side dev mode (npm run admin) binds 127.0.0.1 by default regardless.

Docker-socket trade-off: the admin service mounts /var/run/docker.sock so Save & Apply can run docker compose up -d --no-build api worker against the real stack from inside the container (it never recreates the admin service itself -- that would kill the container mid-request). This gives the admin container control of the host's Docker daemon, the same pattern used by tools like Portainer. Accepted because the panel is a personal tool on a trusted network -- combined with the reachability note above, treat "who can open the panel" as "who can administer this Docker host".

Development

npm install
npm run build        # tsc -> dist/bin/{api,worker,admin}.js, copies
                      #   src/admin/ui -> dist/admin/ui (static UI assets)
npm run test          # full suite -- REQUIRES Docker (spins up redis:7-alpine
                      #   via testcontainers for the BullMQ retry/dead-letter
                      #   integration test); set REDIS_TEST_URL to reuse a
                      #   running Redis instead of a container
npm run test:unit     # no-Docker fast subset (src unit tests only)
npm run test:integration  # just the Redis-backed queue integration test
npm run dev:api        # tsx, no build step
npm run dev:worker

Verified

docker compose up -d --build was run end-to-end against a real ntfy.sh topic:

• docker compose ps -- all 3 services (redis, api, worker) up, api healthcheck healthy.

• curl http://localhost:8080/health -> 200 {"status":"ok","redis":true}.

• curl -X POST http://localhost:8080/notify -H "Authorization: Bearer <token>" -d '{"title":"notify-hub","message":"smoke test"}' -> 202 {"jobId":"1"}.

• Worker log: {"channel":"ntfy","msg":"sending notification"} followed by {"channel":"ntfy","msg":"notification sent"}.

• Confirmed on the ntfy side too: curl "https://ntfy.sh/<topic>/json?poll=1" returned the exact message: {"title":"notify-hub","message":"smoke test", ...}.

If your environment can't reach the public internet (ntfy.sh), point NTFY_URL at a self-hosted ntfy instance instead and repeat the same smoke steps.

Contributing

Contributions are welcome — the most useful one is a new channel adapter. Each channel is a small self-contained file implementing one interface:

1. Add src/channels/adapters/<name>-channel.ts implementing NotificationChannel (a single send(notification) method) plus its ChannelRegistryEntry (factory + required env keys).

2. Register it with one line in src/channels/channel-registry.ts.

3. Add unit tests next to it (happy path + error path, using the fakes in test/helpers/fakes.ts — no real network in tests).

4. npm run test:unit must pass; open a PR.

Ideas: Gotify, Matrix, Pushover, Signal, Mattermost, Rocket.Chat, SMS gateways. Bug reports and docs fixes are equally appreciated — open an issue.

License

MIT © Richard Campos