ntfy-mcp 是 ntfy 的 Model Context Protocol（MCP）服务器。ntfy 是一个发布-订阅通知服务，只需一个 HTTP 请求即可向手机发送推送消息。该服务器让 Claude Code、Claude Desktop、Codex 等 MCP 客户端可以向用户发送通知、读回已发送的内容、在任务运行期间原地修订一条通知，并且在拥有管理员账号时创建账户、授予或撤销账户对主题的访问权限——这些操作原本需要在服务器上使用 ntfy 命令行完成。
主要能力
- 发布通知、读取缓存消息、原地更新通知：publish_message 返回的 id 同时也是该通知的序列 id，update_message 可原地替换其内容，因此订阅者看到的是一条通知从“building”变为“deployed”，而不是收集到五条。
- 用户与主题访问管理：使用管理员账号可创建账户并授予或撤销其对主题的访问权限。
- 工具数量可调：最多注册十三个工具，也支持通过 NTFY_ALLOW_TOOLS=essential 注册精选的六个工具（get_server_info、check_topic_access、publish_message、list_messages、get_message、update_message）。六件套中有四个是读取工具，因此在 NTFY_READ_ONLY=true 下依然可用。从六个工具中选择比从十三个中选择更可靠。
- 结构化输出：每个工具都声明 outputSchema，并在文本块之外返回 structuredContent，使客户端无需解析文字即可使用结果。
使用方式
- 环境变量：NTFY_TOPICS 用于限定该服务器可触碰的主题，并在工具省略主题时提供默认值。NTFY_ALLOW_TOOLS 和 NTFY_DENY_TOOLS 接受逗号分隔的工具名，末尾的 * 可匹配整个工具族。
- 凭证：凭证是可选的，允许匿名访问的实例无需凭证。同时设置 NTFY_TOKEN 与 NTFY_USERNAME / NTFY_PASSWORD 会在启动时被拒绝，而非按优先级规则解决，以避免凭证归属不明确。建议使用 https://，纯 http 下凭证未加密（basic auth 只是 base64，并非加密），除非主机为本地，否则服务器会打印警告。自签名证书建议使用正规内部 CA，而非 NTFY_INSECURE_TLS。
- 未配置时：服务器仍会启动并列出其工具（便于注册表和检查器内省），但每次调用都会以设置说明失败，而不会访问 API。
- 通过 mcp-hub：无法生成本地进程的客户端（ChatGPT connectors、Web 版 Claude、Cursor、LibreChat）可通过 mcp-hub 访问 ntfy-mcp。一个容器通过 Streamable HTTP 服务多个 stdio MCP 服务器，在单一密码后提供 OAuth 2.1 登录，并为无法使用 OAuth 的客户端提供长期令牌。其 /hub 端点将所有服务器置于六个元工具之后。
适用场景
- 让 MCP 客户端在长时间任务运行期间发送进度通知，并保持为同一条通知。
- 需要读回已发送消息或检查主题访问权限的场景。
- 拥有管理员账号时，通过 MCP 客户端管理 ntfy 用户及其主题授权。
限制与注意事项
- 写入默认开启：NTFY_READ_ONLY 默认为 false。设置 NTFY_READ_ONLY=true 时不注册写入工具；NTFY_DENY_TOOLS 也可按同一方向做更细的裁剪，被过滤的工具根本不会被构建。
- NTFY_READ_ONLY 解析较为宽松：true、1、yes 均视为只读（不区分大小写），但 NTFY_READ_ONLY=ture 不属于其中，因此仍会启用写入工具。
- 主题名即凭证：在 ntfy 上，知道主题名通常就等于拥有访问控制，应将主题名视为机密。服务器没有提供枚举主题的能力，因为 ntfy 没有此类 API，且枚举结果将等同于凭证列表。get_account 和 list_users 是现有主题名出现的仅有两个位置。
- 读写按主题分别授予：只有写入权限的发布令牌无法轮询其所发布的主题，这是正确配置而非故障。check_topic_access 只测试读取侧，因此该处被拒并不意味着发布会失败。
- 未实现的功能（有意为之）：从已发布消息发送电子邮件或拨打电话；创建、读取或交换访问令牌；流式订阅（/sse、/ws、/raw）；附件上传；预约、计费、Web 推送、邮件与电话验证以及 Matrix 网关。
- 确认提示：在支持 MCP elicitation 的客户端中，delete_messages、delete_user、manage_user_access、create_user 和 update_message 会弹出模型无法代答的对话框；不支持的客户端回退为绑定到确切目标指纹的短期令牌。确认提示不会引用来自 ntfy 的内容，也不会包含 create_user 的密码。
- 返回内容标记为不可信数据：通知中的一切内容均由能向该主题发布的人撰写。该标记出现在报告他人所写内容的四个工具上：list_messages、get_message、get_account、list_users。
- 调用方提供的 URL 必须是 http 或 https。
- 发布者可控制的每个字段都有边界：ntfy 将消息正文限制为 4096 字节，但不限制标题或标签列表，因此这些在此处被限制。
完整指南、工具参考和安全说明位于 ntfy-mcp.ni-c.de（源码在 docs/ 中）。
发布流程：发布由标签驱动。更新 package.json，将 CHANGELOG.md 中的 [Unreleased] 备注移动到新版本下，提交，然后执行发布。发布工作流通过 Trusted Publishing（OIDC，带 provenance）发布到 npm，将多架构容器镜像推送到 GHCR，根据 CHANGELOG 章节创建 GitHub release，并更新官方 MCP 注册表中的条目。
欢迎提交 issue、讨论和 pull request——参见 CONTRIBUTING.md。漏洞请使用私有报告而非公开 issue；策略见 SECURITY.md。
MIT © Willi Thiel
