ntfy

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.

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 ≥ 24
• A reachable ntfy server. Credentials are optional: an instance that allows anonymous access needs none.

Configuration

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 any case — a protection switch is parsed generously on purpose. But NTFY_READ_ONLY=ture is not any of them, and because the default is permissive it leaves the write tools enabled, where in imap-mcp it would fail closed.
• A client that can publish can publish anywhere on the instance unless you say otherwise. Confirmation tokens do not help against that — publishing is not a destructive operation. NTFY_TOPICS is the control that does.

The recommended shape for anything unattended:

NTFY_TOPICS=deploys                 # the server can only touch this topic

NTFY_ALLOW_TOOLS=essential # or: NTFY_DENY_TOOLS=delete_messages,create_user,delete_user,manage_user_access

On a self-hosted instance, also give the server its own ntfy account with write-only access to exactly the topics it needs.

Choosing which tools load

NTFY_ALLOW_TOOLS and NTFY_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset — get_server_info, check_topic_access, publish_message, list_messages, get_message and update_message — marked as such in the tool reference. Four of the six are read tools, so the preset stays useful under NTFY_READ_ONLY=true.

NTFY_ALLOW_TOOLS=essential

NTFY_ALLOW_TOOLS=publish_message,list_messages NTFY_DENY_TOOLS=delete_*,create_user,manage_user_access

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under NTFY_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

Claude Code

claude mcp add ntfy-mcp -- npx -y @ni-c/ntfy-mcp

Claude Desktop

{

"mcpServers": { "ntfy-mcp": { "command": "npx", "args": ["-y", "@ni-c/ntfy-mcp"], "env": { "NTFY_URL": "https://ntfy.example.net", "NTFY_TOKEN": "…", "NTFY_TOPICS": "deploys" } } } }

Codex

[mcp_servers.ntfy-mcp]

command = "npx" args = ["-y", "@ni-c/ntfy-mcp"] env = { NTFY_URL = "https://ntfy.example.net", NTFY_TOKEN = "…", NTFY_TOPICS = "deploys" }

Docker

docker run -i --rm \

-e NTFY_URL=https://ntfy.example.net -e NTFY_TOPICS=deploys \ ghcr.io/ni-c/ntfy-mcp

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches ntfy-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{

"mcpServers": { "ntfy-mcp": { "command": "npx", "args": ["-y", "@ni-c/ntfy-mcp"], "env": { "NTFY_URL": "https://ntfy.example.net", "NTFY_TOKEN": "…", "NTFY_TOPICS": "alerts", "NTFY_ALLOW_TOOLS": "essential" }, "denyTools": ["delete_messages"] } } }

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools

* marks the essential preset.

| check_topic_access * | Whether the credentials may subscribe to a topic — se