ni-c/ntfy-mcp

A Model Context Protocol (MCP) server for
ntfy, the pub-sub notification service that sends push messages
to your phone with an HTTP request and nothing else.
Lets MCP clients like Claude Code, Claude Desktop or Codex send you notifications,
read back what was sent, revise a notification in place while a job runs, and — with
an admin account — create accounts and grant or revoke their access to topics, which
otherwise means the ntfy command line on the server.
Thirteen tools is the ceiling, not the floor: NTFY_ALLOW_TOOLS=essential registers
a curated six instead, and a model picks the right tool far more reliably from six
than from thirteen — see choosing which tools load.
is resolved against the colour scheme of the page showing it, so GitHub
picks the variant that matches its own theme toggle. npm strips and
when it sanitises the README and keeps the , which is why that
fallback brings its own dark card instead of relying on a media query.
The URLs must stay absolute: a relative path is simply invisible on npm. -->
What makes it different
**A progress report stays one notification.** The id publish_message returns is
also the notification's sequence id, and update_message replaces its content in
place — subscribers watch one notification change from "building" to "deployed"
instead of collecting five.
**NTFY_TOPICS is the fence.** On ntfy a topic name is a bearer credential:
knowing it is often the whole of the access control. One variable names the topics
this server may touch and supplies the default when a tool omits one, so the name
stays out of the tool arguments and out of the model's context.
Requirements
- Node.js ≥ 22
- A reachable **ntfy** server. Credentials are optional: an instance that allows
anonymous access needs none.
Configuration
| Variable | Required | Description |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NTFY_URL | yes | Base URL, e.g. https://ntfy.example.net. There is deliberately no default — https://ntfy.sh would make a misconfiguration publish to the public internet. |
| NTFY_TOKEN | no | Access token (tk_…). Mutually exclusive with the two below. |
| NTFY_USERNAME | no | Basic-auth user. Must be set together with NTFY_PASSWORD. |
| NTFY_PASSWORD | no | Basic-auth password. |
| NTFY_TOPICS | no | Comma-separated topics this server may use. The first is the default when a tool omits one, and the list restricts every tool, read and write — access grants included. |
| NTFY_READ_ONLY | no | true, 1 or yes (any case) registers only the six read tools. Default false. |
| NTFY_ALLOW_TOOLS | no | Comma-separated tool names, list_* prefixes, or essential for a curated preset |
| NTFY_DENY_TOOLS | no | Same syntax; removed from whatever NTFY_ALLOW_TOOLS left |
| NTFY_INSECURE_TLS | no | true accepts self-signed certificates (scoped to this connection) |
Setting NTFY_TOKEN together with NTFY_USERNAME/NTFY_PASSWORD is refused at
startup rather than resolved by a precedence rule: which credential is in force must
never be ambiguous.
> **Use https://.** Over plain http the credentials travel unencrypted — basic
> auth is base64, not encryption — and the server prints a warning unless the host is
> local. For self-signed certificates prefer a proper internal CA over
> NTFY_INSECURE_TLS.
Without configuration the server still starts and lists its tools (so registries and
inspectors can introspect it), but every call fails with setup instructions instead
of reaching the API.
Writes are on by default
NTFY_READ_ONLY defaults to false. ntfy exists to publish, and a read-only default
would ship a notification server that cannot notify — this is the opposite of
imap-mcp, where the same variable defaults to
true because a mailbox is an irreplaceable archive.
Two consequences worth knowing:
- **A typo still fails open.** true, 1 and yes are all read as read-only, in