ntfy-mcp-server

<div align="center"> <h1>ntfy-mcp-server</h1> <p><b>Send, manage, and replay ntfy push notifications via MCP. STDIO or Streamable HTTP.</b> <div>4 Tools • 1 Resource</div> </p> </div>

<div align="center">

   

  

</div>

<div align="center">

  

</div>

---

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:

| Tool Name | Description | |:----------|:------------| | ntfy_publish_message | Send or update a push notification on an ntfy topic. | | ntfy_manage_message | Clear or delete a previously-sent notification by sequence_id. | | ntfy_fetch_messages | Poll cached messages from one or more topics with optional filters. | | ntfy_search_emoji_tags | Look up ntfy emoji tag short codes for use in tags. |

---

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, on STDIO clients that support MCP elicitation

---

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.

• STDIO clients that support MCP elicitation prompt the user to confirm the topic, sequence_id, and operation before the event fires; 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

| Type | Name | Description | |:---|:---|:---| | Resource | ntfy://{topic} | Snapshot of a topic — latest 20 messages from the past 1 hour, plus the topic's browser URL. Same normalized message shape as ntfy_fetch_messages: ISO 8601 timestamps and ~500-char body truncation. |

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. Clients that support MCP elicitation get a prompt naming the exact target; on clients that don't, the tool annotations remain the only signal. Reachable over STDIO today — the Streamable HTTP transport builds a fresh server per request, so a client's advertised capabilities do not survive to the tool call and no prompt is issued
• 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 <https://ntfy.sh/account>.

{
  "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

1. Navigate into the directory:

cd ntfy-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

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

Configuration

| Variable | Description | Default | |:---------|:------------|:--------| | NTFY_SERVERS | JSON array of { baseUrl, authToken? \| authUsername?+authPassword? } entries — one per ntfy server. First entry is the default base. Auth is scoped to the entry's baseUrl; per-call base_url overrides that match a registered base forward that server's auth. Use this when you need more than one authenticated server in a single process; it takes precedence over the single-server vars below. | — | | NTFY_BASE_URL | Single-server shorthand — base URL of the ntfy server (no trailing slash). Used when NTFY_SERVERS is unset. | https://ntfy.sh | | NTFY_DEFAULT_TOPIC | Topic used when a tool call omits topic. | — | | NTFY_AUTH_TOKEN | Bearer access token (tk_…) for the single-server shorthand. Mutually exclusive with NTFY_AUTH_USERNAME / NTFY_AUTH_PASSWORD. | — | | NTFY_AUTH_USERNAME | Basic-auth username for the single-server shorthand — required together with NTFY_AUTH_PASSWORD. | — | | NTFY_AUTH_PASSWORD | Basic-auth password for the single-server shorthand — required together with NTFY_AUTH_USERNAME. | — | | NTFY_REQUEST_TIMEOUT_MS | Per-request HTTP timeout in milliseconds. | 15000 | | NTFY_MAX_RETRIES | Max retry attempts for transient upstream failures (5xx, network, 429). | 3 | | NTFY_BLOCK_PRIVATE_HOSTS | When true, a per-call base_url override must resolve to a public address, and its redirects are not followed. Servers registered under NTFY_SERVERS / NTFY_BASE_URL are exempt, so a deliberate LAN target still works. Turn it on where callers you don't control can reach the server. | false | | MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio | | MCP_SESSION_MODE | HTTP session model: stateless, stateful, or auto. | auto | | MCP_HTTP_HOST | HTTP host. | 127.0.0.1 | | MCP_HTTP_PORT | HTTP port. | 3010 | | MCP_HTTP_ENDPOINT_PATH | HTTP endpoint path. | /mcp | | MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none | | MCP_LOG_LEVEL | Log level (RFC 5424). | info | | LOGS_DIR | Directory for file-based logs (Node only; ignored on Workers). | ./logs | | OTEL_ENABLED | Enable OpenTelemetry instrumentation (spans, metrics, completion logs). | false |

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, stateless 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

| Directory | Purpose | |:----------|:--------| | src/index.ts | createApp() entry point — registers tools and resources, initializes services. | | src/config | Server-specific environment variable parsing (NTFY_) with Zod. | | src/mcp-server/tools | Tool definitions (.tool.ts). | | src/mcp-server/resources | Resource definitions (*.resource.ts). | | src/services/ntfy | ntfy HTTP client, types, and error classifier. | | src/services/emoji-tags | Bundled emoji short-code reference and lookup service. | | docs/ntfy | Mirrored upstream ntfy API docs (pinned commit in SOURCES.md). | | tests/ | Unit and integration tests mirroring src/. |

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.