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:

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

---

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.

---

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
• Long bodies truncated to ~500 chars with messageTruncated reporting the dropped count

---

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.

Resources and prompts

Type	Name	Description
Resource	ntfy://{topic}	Snapshot of a topic — last 20 messages from the past 1 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.

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: