ntfy-mcp-server
Send, manage, and replay ntfy push notifications via MCP. STDIO or Streamable HTTP.
4 Tools • 1 Resource
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:
