ntfy-mcp-server

Tools

Four tools covering the ntfy publish/subscribe surface — message lifecycle (publish, manage, fetch) plus an emoji-tag lookup that feeds the publish tool's `tags` field:

`ntfy_publish_message`

Send or update a push notification on an ntfy topic. Topics are created on first publish — treat the topic name as a secret because anyone who knows it can publish or subscribe.

• Full publish-parameter coverage — `title`, `priority` (1–5), `tags`, `click`, `attach`, `icon`, `filename`, `markdown`, `delay`, `email`, `call`, `cache`, `firebase`
• Up to three discriminated action buttons (`view`, `broadcast`, `http`, `copy`) per message
• Update or replace previously-sent messages by passing the original `sequence_id`
• Per-call `base_url` override that forwards credentials only when the override matches a registered server (`NTFY_BASE_URL` or an `NTFY_SERVERS` entry); otherwise the request goes out unauthenticated, so credentials never leak to alternate hosts
• Publishes carrying `email`, `call`, or a `broadcast` / `http` action button ask the user to confirm the specific recipient or target first — the call comes back requesting that confirmation, and the message goes out only when it is reissued with the answer attached

`ntfy_manage_message`

Clear (mark read & dismiss) or delete a previously-sent ntfy notification by `sequence_id`. Append-only — the original message stays in cache, and a `message_clear` / `message_delete` event is emitted to subscribers. Idempotent.

• Every call asks the user to confirm the topic, `sequence_id`, and operation before the event fires — the first call comes back requesting that confirmation, and declining fails the call with `consent_declined`

`ntfy_fetch_messages`

Poll cached messages from one or more topics with optional filters. Returns a snapshot, not a live stream — use it to confirm delivery, replay missed alerts, or audit topic activity.

• Comma-separated multi-topic queries (e.g. `alerts,backups,phil_alerts`)
• Filter by `since` (duration / timestamp / message ID / `all` / `latest`), `priority`, `tags`, `id`, `title`, `message`, scheduled-only
• Default window `10m`, default limit 20 messages per response, hard cap 100 — over-limit windows keep the newest `limit` messages, listed oldest-first
• Long bodies truncated to ~500 chars with `messageTruncated` reporting the dropped count; refetch with a message `id` to read that one in full

`ntfy_search_emoji_tags`

Substring search over the bundled ntfy emoji-tag reference. Returns the `tag` strings ready to plug into `ntfy_publish_message`'s `tags` field. Without a query, returns the first slice of the full reference; `offset` pages through matches beyond the `limit` cap.

Resources and prompts

`ntfy_fetch_messages` covers the same topic data with custom windows and filters when the resource's fixed defaults aren't enough.

Features

Built on `@cyanheads/mcp-ts-core`:

• Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
• Typed error contracts via `ctx.fail(reason, …)` plus framework error factories (`forbidden`, `notFound`, `validationError`, …)
• Pluggable auth: `none`, `jwt`, `oauth`
• Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

ntfy-specific:

• Wraps ntfy's HTTP API with retry-aware client (`withRetry` + per-request timeout)
• Per-server scoped auth — credentials are bound to each registered base URL (`NTFY_BASE_URL` or per-entry under `NTFY_SERVERS`); per-call `base_url` overrides forward auth only when the override matches a registered server, and go out unauthenticated otherwise
• User confirmation before side effects that leave the notification drawer — a clear/delete, or a publish carrying `email`, `call`, or a `broadcast` / `http` action button. The tool returns a confirmation request naming the exact target, and acts only on the reissued call that carries an approval. Enforced on both STDIO and Streamable HTTP; a client that cannot present the prompt gets an error instead of an unasked side effect
• Optional SSRF guard on `base_url` overrides (`NTFY_BLOCK_PRIVATE_HOSTS`) — resolves the host and blocks every reserved destination it answers on (loopback, RFC 1918, RFC 6598 mesh space, link-local, and the IPv6 equivalents), then refuses redirects, with registered servers exempt
• Bundled emoji-tag reference, regenerated from upstream `docs/ntfy/emojis.md` via `scripts/build-emoji-tags.ts`
• Mutually-exclusive auth modes (bearer token *or* basic auth) validated at config-load time

Getting started

Add the following to your MCP client configuration file. Public ntfy.sh works out of the box without an account; for protected topics, generate an access token at .

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["ntfy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "NTFY_DEFAULT_TOPIC=your-topic-name",
        "ghcr.io/cyanheads/ntfy-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NTFY_DEFAULT_TOPIC=your-topic bun run start:http
# Server listens at http://127.0.0.1:3010/mcp

Prerequisites

• Bun v1.3.11 or higher (or Node.js v24+).
• A topic name on an ntfy server. Public `ntfy.sh` requires no account; self-hosted instances and protected topics may need a bearer token or basic-auth credentials.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/ntfy-mcp-server.git

2. Navigate into the directory:

cd ntfy-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env and set NTFY_DEFAULT_TOPIC (and auth, if needed)

Configuration

See `.env.example` for the full list of optional overrides.

Running the server

Local development

• Build and run:

# One-time build
  bun run rebuild

  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

bun run devcheck     # Lint, format, typecheck, security, changelog sync
  bun run test         # Vitest test suite
  bun run lint:mcp     # Validate MCP definitions against spec

Docker

docker build -t ntfy-mcp-server .
docker run --rm -e NTFY_DEFAULT_TOPIC=your-topic -p 3010:3010 ntfy-mcp-server

The Dockerfile defaults to HTTP transport, stateful session mode, and logs to `/var/log/ntfy-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.

Project structure

Development guide

See `CLAUDE.md` for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no `try/catch` in tool logic
• Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
• Per-tool `errors[]` contracts stay inline — repetition is intended for locality

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.