Ntfy MCP Server

---

概述

通过 ntfy 向手机或桌面发送推送通知。发布、更新和管理通知，轮询主题的近期历史记录，并查询标签使用的表情符号简码。

工具

工具	描述
ntfy_publish_message	在 ntfy 主题上发送或更新推送通知。
ntfy_manage_message	根据 sequence_id 清除或删除先前发送的通知。
ntfy_fetch_messages	使用可选筛选条件轮询一个或多个主题的缓存消息。
ntfy_search_emoji_tags	查询 ntfy 表情符号标签简码，以便用于 tags。

资源

资源	描述
ntfy://{topic}	主题快照——过去一小时内的最新 20 条消息，以及该主题的浏览器 URL。

当资源固定的默认设置无法满足需求时，ntfy_fetch_messages 可通过自定义时间范围和筛选条件获取相同主题数据。

功能参考

ntfy_publish_message _工具

• 首次发布时会创建主题——请将主题名称视为机密；任何知道名称的人都可以发布或订阅
• 支持 title、priority（1–5）、tags、click、attach、icon、filename、markdown、delay、email、call、cache、firebase，以及最多三个操作按钮（view、broadcast、http、copy）；消息正文上限为 4096 字节，正文为空时默认为 triggered；传入原始 sequence_id 可更新已发送的消息
• 使用 email、call 或 broadcast/http 按钮发布时，会要求用户在发送前确认目标
• 单次调用传入的 base_url 仅在匹配已注册的服务（NTFY_BASE_URL 或 NTFY_SERVERS 条目）时才会使用凭据；否则请求不进行身份验证

ntfy_manage_message _工具

• operation：clear 会将通知标记为已读并将其关闭（订阅者会收到 message_clear）；delete 会将其从通知抽屉中移除（订阅者会收到 message_delete）
• 每次调用都会先要求用户确认主题、sequence_id 和操作；如果用户拒绝，则会以 consent_declined 失败
• 原始消息会保留在缓存中，重复执行操作是安全的；ntfy.sh 接受未知的 sequence_id，更严格的部署则会返回 not_found

---

ntfy_fetch_messages _工具

• 返回快照，而非实时流；接受逗号分隔的主题（例如 alerts,backups），并支持 since（时长／时间戳／消息 ID／all／latest）、priority、tags、id、title、message 和仅限计划消息等筛选条件
• 默认时间窗口为 10m，默认限制为 20 条，每次调用最多 100 条；较大的时间窗口会返回最新的 limit 条消息，并提供 totalCount 和 nextCursor，可将其作为 cursor 传回
• 消息正文会在约 500 个字符处截断（messageTruncated 会给出省略的字符数）；如需获取完整文本，请使用 id 重新获取
• 如果 ntfy 截断了重放内容，则会设置 upstreamTruncated；如果服务器未返回 ntfy 消息流，则会以 upstream_malformed 失败

---

ntfy_search_emoji_tags _工具

• 对标签名称进行不区分大小写的子串匹配；省略 query 可按顺序列出参考列表
• limit 默认为 25，每次调用最多 200 条；使用 offset 翻页，并参考 totalCount
• 返回的 tag 字符串可直接传入 ntfy_publish_message 的 tags
• 默认启用；设置 NTFY_ENABLE_EMOJI_TAGS=false 可将其从 tools/list 中移除

---

ntfy://{topic} _资源

• 固定快照：过去一小时内的最新 20 条消息，以及该主题的浏览器 URL；格式与 ntfy_fetch_messages 相同（包括 upstreamTruncated）
• 如需自定义时间窗口或筛选条件，请使用 ntfy_fetch_messages

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none／jwt／oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

ntfy 特有功能：

• 支持重试的 ntfy 客户端，提供单次尝试超时；每次调用最长为 50 s，可在 MCP 客户端默认的 60 s 超时前完成
• 按服务器进行身份验证：凭据绑定到每个已注册的基础 URL（NTFY_BASE_URL 或 NTFY_SERVERS 条目）；bearer-token 和 basic-auth 模式互斥
• 在 stdio 和 Streamable HTTP 上，执行清除／删除操作，或通过 email、call 或 broadcast／http 按钮发布消息之前，都会要求用户确认
• 可选的 SSRF 防护，用于检查 base_url 覆盖项（NTFY_BLOCK_PRIVATE_HOSTS）；已注册服务器不受此限制
• 内置 emoji 标签参考列表，通过 scripts/build-emoji-tags.ts 从上游 docs/ntfy/emojis.md 重新生成

适用于 Agent 的输出：

• 发布和管理操作会回显解析后的主题、ID 和时间戳；获取操作也会回显解析后的 since 和已应用的筛选条件
• 类型化的 reason 代码（consent_declined、forbidden_topic、rate_limited、not_found、payload_too_large 等）让调用方可以根据失败类型进行分支处理
• 获取和 emoji 搜索会报告 truncated、totalCount，并通过 notice 说明下一步操作（将 nextCursor 作为 cursor 传入，或递增 offset）

开始使用

将以下内容添加到 MCP 客户端配置文件中。无需账户即可直接使用公共 ntfy.sh；对于受保护的主题，请前往 https://ntfy.sh/account 生成访问令牌。

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

也可以使用 npx（无需 Bun）：

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

也可以使用 Docker：

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "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.4.0 或更高版本（或 Node.js v24+）。
• ntfy 服务器上的主题名称。公共 ntfy.sh 无需账户；自托管实例和受保护的主题可能需要 bearer token 或 basic-auth 凭据。

安装

1. 克隆仓库：

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

2. 进入目录：

cd ntfy-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

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

配置

变量	描述	默认值
NTFY_SERVERS	{ baseUrl, authToken? | authUsername?+authPassword? } 条目的 JSON 数组，每个条目对应一个 ntfy 服务；第一个条目为默认服务。优先级高于下面的单服务变量。	—
NTFY_BASE_URL	单服务简写配置——ntfy 服务的基础 URL（末尾不带斜杠）。当未设置 NTFY_SERVERS 时使用。	https://ntfy.sh
NTFY_DEFAULT_TOPIC	工具调用未提供 topic 时使用的主题。	—
NTFY_AUTH_TOKEN	单服务简写配置的 Bearer 访问令牌（tk_…）。不能与 NTFY_AUTH_USERNAME / NTFY_AUTH_PASSWORD 同时使用。	—
NTFY_AUTH_USERNAME	单服务简写配置的基本身份验证用户名——必须与 NTFY_AUTH_PASSWORD 一起设置。	—
NTFY_AUTH_PASSWORD	单服务简写配置的基本身份验证密码——必须与 NTFY_AUTH_USERNAME 一起设置。	—
NTFY_REQUEST_TIMEOUT_MS	每次尝试的 HTTP 超时时间，单位为毫秒。每次调用在所有尝试中的总耗时也限制为 50 s。	15000
NTFY_MAX_RETRIES	针对上游临时故障（5xx、网络错误、429）的最大重试次数。	3
NTFY_BLOCK_PRIVATE_HOSTS	当值为 true 时，每次调用的 base_url 覆盖值必须解析为公共地址，并且不会跟随重定向。已注册的服务不受此限制。如果不受你控制的调用方可以访问此服务，请启用此选项。	false
NTFY_ENABLE_EMOJI_TAGS	设置为 false 可禁用 ntfy_search_emoji_tags。无法识别的值会导致启动失败。	true
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless。通过 HTTP 时，此服务要求使用 stateful（auto 会解析为该模式）；启动时会拒绝 stateless。在 stdio 模式下忽略此项。	stateful
MCP_HTTP_HOST	HTTP 主机。	127.0.0.1
MCP_HTTP_PORT	HTTP 端口。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径。	/mcp
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_REQUEST_STATE_KEY	HTTP 模式下建议设置。用于对 consent requestState 进行封装、有效期为 900 s 的密钥（≥ 32 字节，例如 openssl rand -base64 32；每个实例必须使用相同的密钥）。无效或过期的状态会被拒绝，并返回 -32602 invalid_request_state。	—
STORAGE_PROVIDER_TYPE	consent 记录的存储位置（TTL 为 600 s）。多实例 HTTP 部署需要使用共享存储：filesystem（共享卷）、supabase 或 cloudflare-d1，不能使用 cloudflare-kv。	in-memory
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	基于文件的日志目录（仅适用于 Node；在 Workers 上忽略）。	./logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果，按键名进行脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值为 16384）以内。自由格式值中的密钥不会被脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩（跟踪跨度、指标、完成日志）。	false

完整的可选覆盖项列表请参阅 .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

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 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口 — 注册工具和资源，初始化服务。
src/config	使用 Zod 解析服务专属环境变量（NTFY_*）。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/services/ntfy	ntfy HTTP 客户端、类型和错误分类器。
src/services/emoji-tags	内置的表情符号短代码参考和查询服务。
docs/ntfy	镜像的上游 ntfy API 文档（固定提交见 SOURCES.md）。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理程序抛出错误，框架捕获错误 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出模式；绝不伪造缺失字段
• 每个工具的 errors[] 契约保持内联 — 有意重复以便就近查看

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。