io.github.cyanheads/ntfy-mcp-server

---

Overview

Push notifications over the ntfy pub/sub HTTP API. Publish, update, and manage notifications, poll cached topic history, and look up emoji short codes for tags from any MCP client. Runs as a stdio process or a local Streamable HTTP server.

Tools

Tool	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.

Resources

Resource	Description
ntfy://{topic}	Snapshot of a topic — latest 20 messages from the past hour, plus the topic's browser URL.

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

Capability reference

ntfy_publish_message _tool

• Topics are created on first publish — treat the topic name as a secret; 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; message body capped at 4096 bytes (non-ASCII characters cost more), empty body defaults server-side to triggered
• Up to three discriminated action buttons (view, broadcast, http, copy) per message
• Update or replace a previously-sent message by passing the original sequence_id
• Per-call base_url override forwards credentials only when it matches a registered server (NTFY_BASE_URL or an NTFY_SERVERS entry); otherwise the request goes out unauthenticated
• Publishes carrying email, call, or a broadcast/http action button ask the user to confirm the specific target first — the call returns a confirmation request, and sends only once reissued with the answer

---

ntfy_manage_message _tool

• operation: clear marks the notification read & dismisses it (subscribers see message_clear); delete removes it from the drawer (subscribers see message_delete)
• Append-only — the original message stays in cache; re-issuing the same operation is safe, though a fresh event fires each call
• Every call asks the user to confirm the topic, sequence_id, and operation before the event fires — the first call returns that confirmation request, and declining fails with consent_declined
• ntfy.sh accepts an unknown sequence_id without error; stricter ntfy deployments return a not_found failure instead

---

ntfy_fetch_messages _tool

• 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 _tool

• Substring match against tag names, case-insensitive; omit query to list the reference from the start in its documented order
• limit default 25, max 200; offset pages past the cap using the returned totalCount
• Returned tag strings plug directly into ntfy_publish_message's tags field

---

ntfy://{topic} _resource

• Fixed snapshot — 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, ~500-char body truncation)
• For custom windows, filters, or replay, use ntfy_fetch_messages instead

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

ntfy-specific:

• Wraps ntfy's HTTP API with a retry-aware client (withRetry + per-request timeout)
• Per-server scoped auth — credentials bind to each registered base URL (NTFY_BASE_URL or an NTFY_SERVERS entry); mutually-exclusive bearer-token / basic-auth modes validated at config load; a per-call base_url override forwards auth only when it matches a registered server
• 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 — enforced on both stdio and Streamable HTTP
• Optional SSRF guard on base_url overrides (NTFY_BLOCK_PRIVATE_HOSTS) — blocks loopback, RFC 1918, RFC 6598 mesh, link-local, and IPv6 equivalents, then refuses redirects; registered servers are exempt
• Bundled emoji-tag reference, regenerated from upstream docs/ntfy/emojis.md via scripts/build-emoji-tags.ts

Agent-friendly output:

• Provenance — ntfy_publish_message and ntfy_manage_message echo back the resolved topic, ID, and timestamp; ntfy_fetch_messages also echoes the resolved since and applied filters
• Discriminated outputs — typed reason codes (consent_declined, forbidden_topic, rate_limited, not_found, payload_too_large, and more) on every tool's error contract let callers branch on failure mode instead of parsing error text
• Truncation and paging guidance — ntfy_fetch_messages and ntfy_search_emoji_tags report a truncated flag plus a notice naming the exact next step (widen since, raise limit, advance offset) instead of silently dropping results

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 npx (no Bun required):

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "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.4.0 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

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: auto, stateful, or stateless. This server requires stateful over HTTP — the consent prompt on destructive and outbound calls is a multi-round-trip request that a 2025-era HTTP client can only complete over a live session — so an HTTP start with stateless is refused. auto resolves to stateful; stdio ignores the setting.	stateful
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, 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

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 are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.