ntfy-mcp

ntfy-mcp is a Model Context Protocol (MCP) server for ntfy. ntfy is a publish-subscribe notification service that can send push messages to a phone with just one HTTP request. This server lets MCP clients such as Claude Code, Claude Desktop, and Codex send notifications to users, read back what was sent, revise a notification in place while a task is running, and, when an admin account is available, create accounts and grant or revoke account access to topics—operations that previously required using the ntfy command line on the server.

Main capabilities

• Publish notifications, read cached messages, and update notifications in place: the id returned by publish_message is also the sequence id of that notification, and update_message can replace its content in place, so subscribers see one notification change from "building" to "deployed" instead of collecting five.
• User and topic access management: with an admin account, you can create accounts and grant or revoke their access to topics.
• Adjustable number of tools: register up to thirteen tools, and also support registering a curated set of six tools via NTFY_ALLOW_TOOLS=essential (get_server_info, check_topic_access, publish_message, list_messages, get_message, update_message). Four of the six are read tools, so they remain available under NTFY_READ_ONLY=true. Choosing from six tools is more reliable than choosing from thirteen.
• Structured output: every tool declares an outputSchema and returns structuredContent in addition to text blocks, so clients can use the results without parsing text.

Usage

• Environment variables: NTFY_TOPICS is used to limit the topics this server can touch and provides a default value when a tool omits the topic. NTFY_ALLOW_TOOLS and NTFY_DENY_TOOLS accept comma-separated tool names, and a trailing * can match an entire tool family.
• Credentials: credentials are optional, and instances that allow anonymous access do not require credentials. Setting both NTFY_TOKEN and NTFY_USERNAME / NTFY_PASSWORD will be rejected at startuprather than resolved by priority rules, to avoid ambiguous credential ownership. It is recommended to use https://，纯 Credentials are not encrypted under http (basic auth is just base64, not encryption), and unless the host is local, the server will print a warning. For self-signed certificates, it is recommended to use a proper internal CA rather than NTFY_INSECURE_TLS.
• When not configured: the server will still start and list its tools (useful for registry and inspector introspection), but every call will fail with setup instructions instead of accessing the API.
• Via mcp-hub: clients that cannot spawn local processes (ChatGPT connectors, Claude on the web, Cursor, LibreChat) can access ntfy-mcp through mcp-hub. A single container serves multiple stdio MCP servers over Streamable HTTP, provides OAuth 2.1 login behind a single password, and offers long-lived tokens for clients that cannot use OAuth. Its /hub endpoint places all servers behind six meta-tools.

Use cases

• Let MCP clients send progress notifications during long-running tasks and keep them as the same notification.
• Scenarios that require reading back sent messages or checking topic access permissions.
• When you have an admin account, manage ntfy users and their topic authorizations through an MCP client.

Limitations and caveats

• Writes are enabled by default: NTFY_READ_ONLY defaults to false. When NTFY_READ_ONLY=true, write tools are not registered; NTFY_DENY_TOOLS can also be used for finer-grained trimming in the same direction, and filtered tools are not built at all.
• NTFY_READ_ONLY parsing is fairly lenient: true, 1, and yes are all treated as read-only (case-insensitive), but NTFY_READ_ONLY=ture is not among them, so write tools will still be enabled.
• The topic name is the credential: on ntfy, knowing the topic name usually amounts to having access control, so topic names should be treated as secrets. The server does not provide the ability to enumerate topics, because ntfy has no such API, and the enumeration result would be equivalent to a list of credentials. get_account and list_users are the only two places where existing topic names appear.
• Read and write are granted separately per topic: a publish token with only write permission cannot poll the topic it publishes to; this is correct configuration, not a failure. check_topic_access only tests the read side, so a denial theredoes not mean the release will fail.
• Unimplemented features (intentional): sending email or making phone calls from published messages; creating, reading, or exchanging access tokens; streaming subscriptions (/sse, /ws, /raw); attachment uploads; scheduling, billing, web push, email and phone verification, and the Matrix gateway.
• Confirmation prompts: in clients that support MCP elicitation, delete_messages, delete_user, manage_user_access, create_user, and update_message display dialogs that the model cannot answer on the user's behalf; unsupported clients fall back to short-lived tokens bound to the exact target fingerprint. Confirmation prompts do not quote content from ntfy and do not include the password for create_user.
• Returned content is marked as untrusted data: everything in a notification is written by whoever can publish to that topic. This marker appears on the four tools that report what others have written: list_messages, get_message, get_account, list_users.
• Caller-provided URLs must be http or https.
• Every field a publisher can control has bounds: ntfy limits the message body to 4096 bytes but does not limit the title or the list of tags, so those are limited here.

The full guide, tool reference, and security notes are at ntfy-mcp.ni-c.de (source in docs/).

Release process: releases are tag-driven. Update package.json, move the [Unreleased] notes in CHANGELOG.md under the new version, commit, then run the release. The release workflow publishes to npm via Trusted Publishing (OIDC, with provenance), pushes multi-architecture container images to GHCR, creates a GitHub release from the CHANGELOG section, and updates the entry in the official MCP registry.

Issues, discussions, and pull requests are welcome—see CONTRIBUTING.md. For vulnerabilities, please use private reporting rather than a public issue; policy in SECURITY.md.

MIT © Willi Thiel