Ntfy MCP Server

ntfy-mcp-server

Send, manage, and replay ntfy push notifications via MCP. STDIO or Streamable HTTP.

4 Tools • 1 Resource

______________________________________________________________________

工具

四个工具涵盖了ntfy发布/订阅表面消息生命周期（发布、管理、获取），加上表情标签查找，为发布工具的 tags 字段：

______________________________________________________________________

ntfy_publish_message

发送或更新关于ntfy主题的推送通知。主题是在首次发布时创建的——将主题名称视为秘密，因为任何知道它的人都可以发布或订阅。

• 完整的发布参数覆盖率-- title, priority (1–5), tags, click, attach, icon, filename, markdown, delay, email, call, cache, firebase
• 最多三个可区分的操作按钮(view, broadcast, http, copy)每条消息
• 通过传递原始消息来更新或替换以前发送的消息 sequence_id
• 每次呼叫 base_url 覆盖，仅当覆盖与注册的服务器匹配时才转发凭据(NTFY_BASE_URL 或a NTFY_SERVERS 条目）；否则，请求将在未经身份验证的情况下发出，因此凭据永远不会泄漏到备用主机

______________________________________________________________________

ntfy_manage_message

清除（标记为已读并取消）或删除之前发送的ntfy通知 sequence_id.Append only-原始消息保留在缓存中 message_clear / message_delete 事件被发送给订阅者。我暂时没有。

______________________________________________________________________

ntfy_fetch_messages

使用可选筛选器轮询来自一个或多个主题的缓存邮件。返回快照，而不是实时流——使用它来确认交付、重放错过的警报或审核主题活动。

• 逗号分隔的多主题查询（例如。 alerts,backups,phil_alerts)
• 筛选依据 since （持续时间/时间戳/消息ID/ all / latest), priority, tags, id, title, message，仅计划
• 默认窗口 10m，默认限制每个响应20条消息，硬上限100
• 长体截断为~500个字符 messageTruncated 报告下降的计数

______________________________________________________________________

ntfy_search_emoji_tags

在绑定的ntfy表情标签引用上进行子字符串搜索。返回 tag 准备插入的字符串 ntfy_publish_messages tags 现场。如果不进行查询，则返回完整引用的第一个片段。

资源和提示

ntfy_fetch_messages 当资源的固定默认值不够时，使用自定义窗口和过滤器覆盖相同的主题数据。

特性

建于 @cyanheads/mcp-ts-core:

• 声明性工具和资源定义——每个原语一个文件，框架处理注册和验证
• 通过键入错误合约 ctx.fail(reason, …) 加上框架错误工厂(forbidden, notFound, validationError, …)
• 可插拔身份验证： none, jwt, oauth
• 可交换存储后端： in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• 带可选OpenTetry跟踪的结构化日志记录
• STDIO和流式HTTP传输

ntfy特定：

• 使用重试软件客户端封装ntfy的HTTP API(withRetry +每次请求超时）
• 每个服务器范围的身份验证--凭据绑定到每个注册的基本URL(NTFY_BASE_URL 或根据以下条目 NTFY_SERVERS)；每次通话 base_url 仅当覆盖与注册的服务器匹配时才覆盖前向身份验证，否则未经身份验证就退出
• 绑定的表情标签引用，从上游重新生成 docs/ntfy/emojis.md 通过 scripts/build-emoji-tags.ts
• 互斥身份验证模式（承载令牌 *或* 基本身份验证）在配置加载时验证

入门

将以下内容添加到MCP客户端配置文件中。Public ntfy.sh无需帐户即可开箱即用；对于受保护的主题，请在以下位置生成访问令牌 .

{
  "mcpServers": {
    "ntfy": {
      "type": "stdio",
      "command": "bunx",
      "args": ["ntfy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}

或者使用Docker：

{
  "mcpServers": {
    "ntfy": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "NTFY_DEFAULT_TOPIC=your-topic-name",
        "ghcr.io/cyanheads/ntfy-mcp-server:latest"
      ]
    }
  }
}

对于Streamable HTTP，设置传输并启动服务器：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NTFY_DEFAULT_TOPIC=your-topic bun run start:http
# Server listens at http://127.0.0.1:3010/mcp

先决条件

• Bun v1.3.11 或更高版本（或Node.js v24+）。
• ntfy服务器上的主题名称。公共 ntfy.sh 不需要帐户；自托管实例和受保护主题可能需要承载令牌或基本身份验证凭据。

安装

1. 克隆存储库：

git clone https://github.com/cyanheads/ntfy-mcp-server.git

1. 导航到以下目录：

cd ntfy-mcp-server

1. 安装依赖项：

bun install

1. 配置环境：

cp .env.example .env
# edit .env and set NTFY_DEFAULT_TOPIC (and auth, if needed)

配置

看 .env.example 查看可选覆盖的完整列表。

运行服务器

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• 运行检查和测试：

  bun run devcheck     # Lint, format, typecheck, security, changelog sync
  bun run test         # Vitest test suite
  bun run lint:mcp     # Validate MCP definitions against spec

码头工人

docker build -t ntfy-mcp-server .
docker run --rm -e NTFY_DEFAULT_TOPIC=your-topic -p 3010:3010 ntfy-mcp-server

Dockerfile默认为HTTP传输、无状态会话模式，并记录到 /var/log/ntfy-mcp-server默认情况下，OpenTelemetry对等依赖项已安装——使用构建 --build-arg OTEL_ENABLED=false 省略它们。

项目结构

发展指南

看 CLAUDE.md 了解开发指南和架构规则。简短版本：

• 处理程序抛出，框架捕获——否 try/catch 工具逻辑
• 使用 ctx.log 对于请求范围的日志记录， ctx.state 适用于租户范围的存储
• 包裹外部API调用：验证原始调用→ 规范化为域类型→ 返回输出模式；永远不要伪造缺失的字段
• 每个工具 errors[] 合约保持内联——重复是为了局部性

贡献

欢迎问题和拉取请求。提交前进行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0--参见 许可证 了解详情。