Ntfy MCP Server

ntfy-mcp-server Send, manage, and replay ntfy push notifications via MCP. STDIO or Streamable HTTP. 4 Tools • 1 Resource • 1 Skill

Overview

Push notifications to your phone or desktop through ntfy. Publish, update, and manage notifications, poll a topic's recent history, and look up emoji short codes for tags.

Tools

Resources

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

Skills

Plugin, npm, Docker, and MCPB installs ship it from skills/; MCP clients that support the Skills extension read it as skill://ntfy-guide/SKILL.md.

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
• Takes title, priority (1–5), tags, click, attach, icon, filename, markdown, delay, email, call, cache, firebase, and up to three action buttons (view, broadcast, http, copy); body capped at 4096 bytes, empty body defaults to triggered; pass the original sequence_id to update a sent message
• Publishes with email, call, or a broadcast/http button ask the user to confirm the target before sending; declining fails with consent_declined
• A per-call base_url gets credentials only if it matches a registered server (NTFY_BASE_URL or an NTFY_SERVERS entry); otherwise the request is unauthenticated
• Failures carry typed reasons: payload_too_large (body, attachment, title, or combined tags over ntfy's limits), invalid_delay, invalid_attachment (malformed attach URL), and unverified_contact (email/call without a verified address or number, or without auth), alongside the shared reasons under Features

ntfy_manage_message tool

• operation: clear marks the notification read and dismisses it (subscribers see message_clear); delete removes it from the drawer (subscribers see message_delete)
• Every call asks the user to confirm the topic, sequence_id, and operation first; declining fails with consent_declined
• The original message stays in cache, and repeating an operation is safe; ntfy.sh accepts an unknown sequence_id, stricter deployments return not_found

ntfy_fetch_messages tool

• Returns a snapshot, not a live stream; accepts comma-separated topics (e.g. alerts,backups, each 1–64 characters) and filters since (duration / timestamp / message ID / all / latest), priority, tags, id, title, message, plus scheduled to include delayed messages
• Default window 10m, default limit 20, at most 100 per call; a larger window returns the newest limit messages with totalCount and a nextCursor to pass back as cursor. Bodies truncate at ~500 chars (messageTruncated gives the dropped count); refetch with id for the full text. upstreamTruncated flags a replay ntfy capped
• Failures carry typed reasons: invalid_since (malformed since value), cursor_not_found (the cursor's message expired, or came from a call with different topics, since, or filters), and upstream_malformed (the response wasn't an ntfy message stream), alongside the shared reasons under Features

ntfy_search_emoji_tags tool

• Case-insensitive substring match on tag names; omit query to list the reference in order
• limit default 25, at most 200 per call; page with offset using totalCount
• Returned tag strings go straight into ntfy_publish_message's tags
• On by default; set NTFY_ENABLE_EMOJI_TAGS=false to remove it from tools/list

ntfy://{topic} resource

• Fixed snapshot: latest 20 messages from the past hour plus the topic's browser URL, in the same shape as ntfy_fetch_messages (including upstreamTruncated)
• For custom windows or filters, use ntfy_fetch_messages

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:

• Retrying ntfy client with a per-attempt timeout, and each call capped at 50 s so it settles before an MCP client's 60 s default
• Per-server auth: credentials bind to each registered base URL (NTFY_BASE_URL or an NTFY_SERVERS entry), with bearer-token and basic-auth modes mutually exclusive
• User confirmation before a clear/delete, or a publish with email, call, or a broadcast/http button, on both stdio and Streamable HTTP
• Optional SSRF guard on base_url overrides (NTFY_BLOCK_PRIVATE_HOSTS); registered servers are exempt
• Bundled emoji-tag reference, regenerated from upstream docs/ntfy/emojis.md via scripts/build-emoji-tags.ts

Agent-friendly output:

• Publish and manage echo the resolved topic, ID, and timestamp; fetch also echoes the resolved since and applied filters
• Typed reason codes let callers branch on failure mode. Shared across the tools and the resource: forbidden_topic (ntfy refused the topic with 401/403: missing or insufficient credentials), rate_limited (429 after retries), upstream_unreachable (network failure, a 5xx that outlasted retries or whose Retry-After the call can't wait out, or no complete answer within the 50 s call deadline; carries retryAfter when ntfy sent one), upstream_malformed (a reply that isn't ntfy's message format or couldn't be read in full; publish and manage don't retry it, since the event may already be out). consent_declined, not_found, and the rest are listed per entry
• Fetch and emoji search report truncated, totalCount, and a notice naming the next step (pass nextCursor as cursor, advance offset)

Getting started

Add it to Claude Code:

claude mcp add ntfy-mcp-server -- npx -y ntfy-mcp-server

For other clients, add this to the MCP config file:

{

"mcpServers": { "ntfy-mcp-server": { "command": "npx", "args": ["-y", "ntfy-mcp-server"] } } }

Public ntfy.sh works without an account. Set NTFY_DEFAULT_TOPIC so calls can omit topic; for protected topics, add NTFY_AUTH_TOKEN (generate one at https://ntfy.sh/account). With claude mcp add, pass each as -e NAME=value after the server name; in JSON, put them under env. For Docker, a source build, or Streamable HTTP, see Running the server.

Configuration

| LOGS_DIR | Directory for file-based logs (