Notifyfan

notifyfan

notifyfan sends notifications through an Apprise API server. A single tool, apprise, fans a message out to the destinations Apprise is configured with: send to one configured tag (or to every configured service), fire a one-off send at raw Apprise URL schemas, and check that the upstream server is alive — all through one action argument instead of a tool per operation. One binary serves a command-line interface and a stdio MCP server.

Configuration

Two environment variables configure the upstream connection:

• APPRISE_URL — the Apprise API server base URL. Defaults to http://localhost:8000.
• APPRISE_TOKEN — optional. When the upstream requires bearer auth, set it and notifyfan sends Authorization: Bearer on every upstream call. It is read from the environment only: it is never a CLI flag and never an MCP tool argument.

The help action works with nothing configured at all.

Install

npx @reneturcios/notifyfan health

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/notifyfan

The container defaults to the MCP server. Pass CLI arguments to use it as a CLI instead.

CLI

notifyfan health

notifyfan status notifyfan help notifyfan notify "Deployment succeeded" --tag ops --title "Deploy complete" --type success notifyfan notify "Standup notes are posted" notifyfan notify-url "mailto://user@example.com" "Build finished" --type info

notifyfan --version

notify needs only a body; omit --tag to send to all configured services. notify-url takes the Apprise URLs first (one string; separate several URLs with commas) and then the body. Exit codes: 0 on success, 1 when a call fails (validation or upstream error), 2 for usage errors.

MCP server

npx -y @reneturcios/notifyfan mcp

MCP client configuration:

{

"mcpServers": { "notifyfan": { "command": "npx", "args": ["-y", "@reneturcios/notifyfan", "mcp"], "env": { "APPRISE_URL": "http://localhost:8000" } } } }

Add APPRISE_TOKEN to the env block only when your Apprise API server requires it.

Tool

Actions:

type is one of info (informational), success (successful operation), warning (non-critical warning), or failure (critical failure or error). Unknown actions, a missing body/urls, and an invalid type are errors raised before any upstream call.

Example call:

{

"name": "apprise", "arguments": { "action": "notify", "body": "Deployment succeeded", "tag": "ops", "title": "Deploy complete", "type": "success" } }

Upstream mapping and known gaps

The action catalogue above is the documented surface. The upstream paths are documented reconstructions from the standard Apprise API: notify posts {body, tag?, title?, type?} to POST /notify, and notify_url posts {urls, body, title?, type?} to the same endpoint — the stateless form; the upstream API has no separate /notify_url route. health reads GET / (the upstream root) and status reads GET /details. Payload fields that were not supplied are omitted, never sent empty. Upstream failures surface the HTTP status plus the upstream message or error string when one is present, and a non-JSON success body is returned as raw text.

• The original's HTTP transport, OAuth, and send_alert prompt are not reproduced; this rebuild is stdio-only.
• No live Apprise API server was used while building: every upstream behaviour is verified against a fake fetch in the test suite.

Development

npm install

npm run build # tsc -> dist/ npm test # node test runner over test/*.test.ts, no network (fake fetch fixtures) npm run dev # run the CLI from source via tsx

License

MIT — see LICENSE.