ntfy-mcp

# ntfy-mcp

<!-- badges: start -->

[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/ntfy-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/ntfy-mcp/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/ntfy-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/ntfy-mcp)
<a href="https://socket.dev/npm/package/@ni-c/ntfy-mcp"><img src="https://socket.dev/api/badge/npm/package/@ni-c/ntfy-mcp" alt="Socket supply-chain report" height="20"></a>
[![Glama score](https://glama.ai/mcp/servers/ni-c/ntfy-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/ntfy-mcp)
<br>
[![npm version](https://img.shields.io/npm/v/%40ni-c%2Fntfy-mcp)](https://www.npmjs.com/package/@ni-c/ntfy-mcp)
[![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Fntfy--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/ntfy-mcp/pkgs/container/ntfy-mcp)
[![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)
<br>
[![docs](https://img.shields.io/badge/docs-ntfy--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://ntfy-mcp.ni-c.de)
[![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
<!-- badges: end -->

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
[ntfy](https://ntfy.sh), 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](#choosing-which-tools-load).

<!-- <picture> is resolved against the colour scheme of the page showing it, so GitHub
     picks the variant that matches its own theme toggle. npm strips <picture> and
     <source> when it sanitises the README and keeps the <img>, 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. -->
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://ntfy-mcp.ni-c.de/architecture-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://ntfy-mcp.ni-c.de/architecture-light.svg">
  <img src="https://ntfy-mcp.ni-c.de/architecture.svg" alt="An MCP client speaks stdio to ntfy-mcp, which publishes notifications and polls the message cache over HTTPS against an ntfy server that pushes them to the subscribed devices" width="800">
</picture>

<!-- Recorded with vhs from docs/demo.tape against a throwaway ntfy container, so it
     reproduces without touching a real instance — see the header of that file. -->

![Demo: listing the tools, publishing a notification and revising it in place through the MCP Inspector CLI](https://ntfy-mcp.ni-c.de/demo.gif)

## 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](https://github.com/ni-c/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:

```sh
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](https://ntfy-mcp.ni-c.de/reference/tools). Four of the six are read
tools, so the preset stays useful under `NTFY_READ_ONLY=true`.

```sh
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](https://mcp-hub.ni-c.de) is
the other answer — its `/hub` endpoint replaces every server's tools with six
meta-tools.

## Installation

### Claude Code

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

### Claude Desktop

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

### Codex

```toml
[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

```sh
docker run