ntfy-me-mcp

ntfy-me-mcp

一个精简的模型上下文协议（MCP）服务，可通过 ntfy 服务（公共或可自托管，并支持令牌）发送和获取通知 📲

概述

ntfy-me-mcp 可让 AI 助手通过 ntfy.sh 服务（公共服务，或支持令牌的可自托管服务）向你的设备发送实时通知。AI 完成任务、遇到错误或达到重要里程碑时，你都能收到通知，无需持续监控。

该服务包含智能功能，例如自动检测 URL 以创建查看操作，以及智能检测 Markdown 格式，让 AI 助手无需额外配置即可创建内容丰富、可交互的通知。

预览	可通过以下平台访问
	名称 链接 / 徽章 ntfy.sh 收录于 ntfy.sh Glama.ai LightNow MseeP.ai Archestra.ai

即将推出……

• 📨 电子邮件：向电子邮箱发送通知（需要配置 ntfy 邮件服务）
• 🖼️ 图片 URL：智能检测图片 URL，并自动将其添加到消息和通知中
• 🏁 等更多功能！

目录

快速入门 - MCP 服务配置

选择与你的客户端相匹配的配置格式。以下所有示例都使用必需变量 NTFY_TOPIC，并将可选的身份验证设置保留为注释，直到你需要使用它们为止。

已通过 Ontheia 测试： Ontheia 是一个可自托管的开源 AI Agent 平台；该平台报告称 ntfy-me-mcp 可与其配合使用，并将其列入兼容的 MCP 服务列表。

要求： npx、全局和本地选项需要 Node.js 24 或更高版本。CI 和 Docker 镜像使用 Node 24。不支持 Node 22 及更早版本（npm 会发出 EBADENGINE 警告）。Docker 选项仅需 Docker。

配置示例

{
  "ntfy-me-mcp": {
    "command": "npx",
    "args": ["-y", "ntfy-me-mcp"],
    "env": {
      "NTFY_TOPIC": "your-ntfy-topic",
      "NTFY_URL": "https://ntfy.sh",
      // "NTFY_TOKEN": "add-your-ntfy-token"
    }
  }
}

{
  "ntfy-me-mcp": {
    "command": "node",
    "args": ["/absolute/path/to/ntfy-me-mcp/build/index.js"],
    "env": {
      "NTFY_TOPIC": "your-ntfy-topic",
      "NTFY_URL": "https://ntfy.sh",
      // "NTFY_TOKEN": "add-your-ntfy-token"
    }
  }
}

{
  "ntfy-me-mcp": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-e",
      "NTFY_TOPIC",
      "-e",
      "NTFY_URL",
      "-e",
      "NTFY_TOKEN",
      "gitmotion/ntfy-me-mcp:latest"
    ],
    "env": {
      "NTFY_TOPIC": "your-ntfy-topic",
      "NTFY_URL": "https://ntfy.sh",
      // "NTFY_TOKEN": "add-your-ntfy-token"
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ntfy-me-mcp": {
      "type": "local",
      "command": ["npx", "-y", "ntfy-me-mcp"],
      "environment": {
        "NTFY_TOPIC": "your-ntfy-topic",
        "NTFY_URL": "https://ntfy.sh",
        // "NTFY_TOKEN": "add-your-ntfy-token"
      }
    }
  }
}

{
  "mcpServers": {
    "ntfy-me-mcp": {
      "command": "npx",
      "args": ["-y", "ntfy-me-mcp"],
      "env": {
        "NTFY_TOPIC": "your-ntfy-topic",
        "NTFY_URL": "https://ntfy.sh",
        "NTFY_TOKEN": "${NTFY_TOKEN:-}"
      }
    }
  }
}

{
  "mcpServers": {
    "ntfy-me-mcp": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "ntfy-me-mcp"],
      "env": {
        "NTFY_TOPIC": "your-ntfy-topic",
        "NTFY_URL": "https://ntfy.sh",
        "NTFY_TOKEN": "your-access-token"
      },
      "tools": ["*"]
    }
  }
}

[mcp_servers.ntfy-me-mcp]
command = "npx"
args = ["-y", "ntfy-me-mcp"]
[mcp_servers.ntfy-me-mcp.env]
NTFY_TOPIC = "your-ntfy-topic"
NTFY_URL = "https://ntfy.sh"
# NTFY_TOKEN = "your-access-token"

{
  "ntfy-me-mcp": {
    "command": "npx",
    "args": ["-y", "ntfy-me-mcp"],
    "env": {
      "NTFY_TOPIC": "your-ntfy-topic",
      "NTFY_URL": "https://your-ntfy-server.com",
      "NTFY_TOKEN": "your-access-token"
    }
  }
}

安装

如果需要直接安装并运行服务（作为上述 MCP 配置的替代方案）：

# 克隆仓库、安装依赖、配置 .env、构建并运行

git clone https://github.com/gitmotion/ntfy-me-mcp.git
cd ntfy-me-mcp
npm install
cp .env.example .env
npm run build
npm start

设置通知接收端

配置

环境变量

复制示例文件创建 .env 文件：cp .env.example .env——请参阅 .env.example 以供参考。

身份验证

// Add this to your VS Code `mcp.json` file, either the user-level file or your workspace `.vscode/mcp.json`
// Set `NTFY_TOKEN` exactly to `"${input:ntfy_token}"` when you want VS Code to treat it as a secure prompt-backed value.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ntfy_token",
      "description": "Ntfy Token",
      "password": true
    }
  ],
  "servers": {
    "ntfy-me-mcp": {
      "command": "npx",
      "args": ["-y", "ntfy-me-mcp"],
      "env": {
        "NTFY_TOPIC": "your-ntfy-topic",
        "NTFY_URL": "https://your-ntfy-server.com",
        "NTFY_TOKEN": "${input:ntfy_token}"
      }
    }
  }
}

工具与用法

ntfy_me：发送通知

使用自然语言

• 使用 AI 助手时，你可以用自然的措辞请求发送通知：

"ntfyme with a summary of the task when complete"
"Send me a notification when the build is complete"
"Notify me when the task is done"
"Alert me after generating the code"
"Message me when the process finishes"
"Send an alert with high priority"

使用示例

{
  "title": "代码生成完成",
  "message": "你的 React 组件已成功创建，
并采用了正确的
TypeScript 类型。",
  "priority": "高",
  "tags": ["white_check_mark", "代码", "react"]
}

{
  "success": true,
  "endpoint": "https://ntfy.sh/ntfymetest"
}

消息参数

{
  title: "Task Complete",
  message: "Regular plain text message",
  markdown: false  // Force disable
}

{
  title: "Build Complete",
  message: "View at https://github.com/org/repo/pull/123"
}

{
  title: "Pull Request Review",
  message: "Ready for final checks",
  actions: [
    {
      action: "view",
      label: "View PR",
      url: "https://github.com/org/repo/pull/123"
    },
    {
      action: "view",
      label: "View Changes",
      url: "https://github.com/org/repo/pull/123/files",
      clear: true
    }
  ]
}

使用自然语言

AI 助手能理解多种请求获取消息的表达方式：

"Show me my recent notifications"
"Get messages from the last hour"
"Find notifications with title 'Build Complete'"
"Search for messages with the test_tube tag"
"Show notifications from the updates topic from the last 24hr"  # needs updates in NTFY_TOPICS_ALLOWLIST (or NTFY_ALLOW_TOPIC_OVERRIDE=true)
"Check my latest alerts"

使用示例

{
  "since": "6h"
}

{
  "success": true,
  "messageCount": 1,
  "topics": {
    "ntfymetest": [
      {
        "id": "On4Jeo1ENDCB",
        "time": 1775859291,
        "event": "message",
        "topic": "ntfymetest",
        "message": "Test",
        "title": "Test",
        "priority": 3,
        "expires": 1775902491
      }
    ]
  }
}

获取参数

两个工具都会为模型返回易于阅读的 content 和机器可读的 structuredContent 对象。对于 ntfy_me_fetch，content 还会以 JSON 格式包含获取到的消息。这些文本来自向主题发布消息的用户，因此应将其视为不可信内容（参见安全）。

无效参数（缺少 title、格式错误的 topic、未知的 priority，……）会在工具运行前由 MCP SDK 的架构验证拒绝。返回结果中，isError: true，并附带一条纯文本 MCP error -32602: Input validation error: … 消息，其中会指出字段及预期格式，且不包含 structuredContent。

工具内部发生故障时，会设置 isError: true，并返回 { "success": false, "error": "<message>" }。错误消息会针对无效的 url 或 topic、身份验证失败（HTTP 401/403）、非 2xx 状态码（... Status code: 500），或网络故障给出具体说明。网络故障会使用 Node 的错误代码标明：未建立连接时为 ... could not connect to the ntfy server (ECONNREFUSED)；连接后请求中断时为 ... the request to the ntfy server failed (ECONNRESET)（通知可能已送达）。其他错误会以通用消息报告（Failed to send ntfy notification / Failed to fetch ntfy messages），因此原始输入或服务端文本绝不会回显给模型。完整的底层错误会写入服务的 stderr 日志。

安全

ntfy-me-mcp 将所有工具参数视为不可信内容，因为这些参数来自可能读取过提示词注入内容的模型。

• URL： 只接受 http:// 和 https:// 服务器 URL，包括来自 url 参数和 NTFY_URL 的 URL。包含嵌入式凭据的 URL（https://user:pass@…）会被拒绝；请使用 NTFY_TOKEN 或 accessToken。
• 启动检查： 如果 NTFY_TOPIC 缺失或无效，或者 NTFY_URL 无效（不是 http(s)，或包含 user:pass@），服务器会在启动时停止。错误会指出变量名并写入 stderr，MCP 客户端会在服务器日志中显示该错误。服务器会先检查这些变量，再记录 NTFY_URL，因此嵌入式凭据绝不会进入日志。
• 令牌和日志： 访问令牌必须是没有空格的可打印 ASCII 字符。错误会写入 stderr，其中的 bearer 值和 URL 凭据会被遮盖。
• 主题： 只能包含字母、数字、_ 和 -，长度最多为 128 个字符。
• 错误消息： 只有一组固定的已知安全消息会传递给模型。其他所有内容都会替换为通用消息，因此攻击者控制的文本绝不会被原样返回（参见 #13）。
• 获取的消息是不可信输入。 ntfy_me_fetch 会将消息内容交给模型，而任何知道公开主题名称的人都可以向该主题发布消息。在 ntfy.sh 上，请使用难以猜测的主题名称，或使用带访问令牌的受保护主题。
• 目标控制： 默认情况下，所有通知和获取操作都会发送到 NTFY_URL 上的 NTFY_TOPIC。Agent 不会获得 topic 或 url 参数，因此提示词注入调用无法将你的消息，或你的主题名称（在公开的 ntfy.sh 上实际上相当于密码），发送到其他位置（参见 #21）。
  • NTFY_TOPICS_ALLOWLIST=alerts,builds 允许 Agent 在你实际订阅的主题和 NTFY_TOPIC 之间进行选择，但不能选择其他主题（参见 #34）。任何其他主题都会在发出请求前被拒绝，不会静默回退。这些主题名称，包括 NTFY_TOPIC，都会出现在工具架构中，因此模型和 MCP 客户端可以看到它们。未设置允许列表时，工具架构中绝不会包含主题名称。在公开的 ntfy.sh 上，主题名称相当于密码，因此只应在你愿意与它们共享名称的情况下使用允许列表，或者使用受保护的主题。
  • NTFY_ALLOW_TOPIC_OVERRIDE=true 和 NTFY_ALLOW_URL_OVERRIDE=true 可分别重新允许使用任意主题或服务器。如果同时设置了 NTFY_TOPICS_ALLOWLIST，则以它为准，而不遵循 NTFY_ALLOW_TOPIC_OVERRIDE。
  • 即使启用了 URL 覆盖，NTFY_TOKEN 也只会发送到 NTFY_URL 服务器。除非调用提供了自己的 accessToken，否则其他服务器不会收到任何凭据。
• 令牌： 相比于将 NTFY_TOKEN 硬编码在共享的配置文件中，建议使用客户端的机密输入（例如 VS Code ${input:…}）或环境变量。

发现了漏洞？请通过 GitHub 安全公告 私下报告，而不要在公开议题中报告。

开发与贡献

欢迎贡献！请参阅 CONTRIBUTING.md，其中包含一般指南、设置步骤等内容。

许可证

本项目采用 GNU General Public License v3.0 许可，详情请参阅 LICENSE 文件。

由 gitmotion 用 ❤️ 制作