Ntfy MCP 服务器

一个设计用于与 ntfy 推送通知服务交互的 MCP (模型上下文协议) 服务器。它使 LLM 和 AI 代理能够向您的设备发送具有广泛自定义选项的通知。

目录

• 概述
• 特性
• 快速开始
• 安装
• 配置
• 项目结构
• 工具
• 资源
• 用例
• 可用脚本
• 贡献
• 许可证

概述

此服务器实现了模型上下文协议 (MCP)，从而实现了 LLM 和外部系统之间的标准化通信。 具体来说，它提供了与 ntfy 推送通知服务的接口。

Ntfy 是一个简单的基于 HTTP 的发布-订阅通知服务，允许您通过简单的 HTTP 请求将通知发送到您的手机或桌面。 通过此 MCP 服务器，像 Claude 这样的 LLM 代理可以通过 ntfy 向您发送通知，而无需直接的 HTTP 访问。

┌───────────┐      ┌───────────┐      ┌───────────┐      ┌─────────┐
│ LLM 代理  │ ────▶│ Ntfy MCP  │ ────▶│ Ntfy      │ ────▶│ 您的    │
│ (Claude)  │      │ 服务器    │      │ 服务      │      │ 设备    │
└───────────┘      └───────────┘      └───────────┘      └─────────┘

特性

• MCP 服务器实现： 使用 @modelcontextprotocol/sdk 构建，可与 LLM 代理无缝集成。
• Ntfy 集成： 提供了一个工具 (send_ntfy) 来发送通知，支持：
  • 消息优先级（1-5 级）
  • Emoji 标签
  • 可点击的操作和按钮
  • 文件附件
  • 延迟发送
  • Markdown 格式
• 资源暴露： 将配置的默认 ntfy 主题公开为 MCP 资源。
• TypeScript： 现代的、类型安全的代码库，具有全面的类型定义。
• 结构化日志记录： 使用 winston 和 winston-daily-rotate-file 进行详细且可轮换的日志记录。
• 配置管理： 使用 dotenv 进行简单的基于环境的配置。
• 实用程序脚本： 包括用于清理构建工件和生成目录结构文档的脚本。
• 错误处理和安全性： 实现了强大的错误处理、输入清理 (sanitize-html) 和安全过滤器 (xss-filters)。

快速开始

1. 先决条件：

   • Node.js (v16+)
   • npm 或 yarn
   • 兼容 MCP 的客户端（Claude Desktop、Cline 等）

2. 安装并运行：

   # 选项 1：通过 npm 安装
   npm install -g ntfy-mcp-server
   
   # 选项 2：克隆存储库并构建
   git clone https://github.com/cyanheads/ntfy-mcp-server.git
   cd ntfy-mcp-server
   npm install
   npm run build
   
   # 创建 .env 文件（可选但推荐）
   cp .env.example .env
   # 编辑 .env 以设置 NTFY_DEFAULT_TOPIC
   
   # 启动服务器
   npm start
   

3. 添加到 MCP 客户端设置： 将服务器添加到您的 MCP 客户端设置文件（请参阅配置）

4. 使用该工具： 连接后，您可以使用 send_ntfy 工具发送通知。

安装

选项 1：NPM 包（推荐）

1. 全局安装该包：

   npm install -g ntfy-mcp-server
   

   这将在全局范围内安装服务器，使其可用作命令行工具。

2. 或者在您的项目中本地安装：

   npm install ntfy-mcp-server
   

   本地安装后，您可以通过 npx 或从 node 运行它。

选项 2：从源代码

1. 克隆存储库：

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

2. 安装依赖项：

   npm install
   

3. 构建项目：

   npm run build
   

配置

环境变量

在项目根目录中基于 .env.example 创建一个 .env 文件：

# Ntfy 配置
NTFY_BASE_URL=https://ntfy.sh  # 可选：您的 ntfy 实例的基本 URL
NTFY_DEFAULT_TOPIC=your_default_topic # 可选：如果请求中未指定主题，则为默认主题

# 应用程序配置
LOG_LEVEL=info # 可选：日志记录级别（debug、info、warn、error）
NODE_ENV=development # 可选：环境（development、production）

MCP 客户端设置

对于 Cline VSCode 扩展

将以下配置添加到您的 Cline MCP 设置文件（通常位于 macOS 上的 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）：

如果全局安装：

{
  "mcpServers": {
    "ntfy": {
      "command": "ntfy-mcp-server",
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

如果从源代码安装：

{
  "mcpServers": {
    "ntfy": {
      "command": "node",
      "args": ["/path/to/ntfy-mcp-server/dist/index.js"],
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

对于 Claude Desktop App

将以下配置添加到您的 Claude Desktop 配置文件（通常位于 macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

如果全局安装：

{
  "mcpServers": {
    "ntfy": {
      "command": "ntfy-mcp-server",
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

如果从源代码安装：

{
  "mcpServers": {
    "ntfy": {
      "command": "node",
      "args": ["/path/to/ntfy-mcp-server/dist/index.js"],
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

对于源代码安装，请将 /path/to/ntfy-mcp-server/dist/index.js 替换为已构建服务器文件的实际绝对路径。 根据您的设置调整 env 变量。

Ntfy 设置

1. 在您的设备上安装 ntfy 应用程序，从 ntfy.sh 或应用商店
2. 在应用程序中订阅您的主题
3. 在您的 MCP 服务器配置中使用相同的主题

项目结构

.
├── .env.example            # 示例环境变量
├── .gitignore              # Git 忽略模式
├── LICENSE                 # 项目许可证 (Apache-2.0)
├── package.json            # 项目元数据和依赖项
├── tsconfig.json           # TypeScript 编译器配置
├── docs/
│   └── tree.md             # 自动生成的目录结构
├── logs/                   # 运行时日志（自动创建）
├── scripts/                # 实用程序脚本
│   ├── clean.ts            # 清理构建工件和日志
│   └── tree.ts             # 生成 docs/tree.md 文件
└── src/                    # 源代码
    ├── index.ts            # 主服务器入口点
    ├── config/             # 配置加载
    ├── mcp-server/         # MCP 服务器逻辑、工具和资源
    │   ├── resources/      # MCP 资源实现
    │   ├── tools/          # MCP 工具实现
    │   └── utils/          # MCP 特定的实用程序
    ├── services/           # 外部服务集成 (ntfy)
    ├── types-global/       # 全局类型定义
    └── utils/              # 常规实用程序函数

工具

send_ntfy

通过 ntfy 服务发送通知消息。

主要参数：

参数	类型	必需	描述
topic	string	是	要发布到的 ntfy 主题。
message	string	是	通知的主要内容（最大 4096 字节）。
title	string	否	通知标题（最大 250 字节）。
tags	string[]	否	用于分类的表情符号或关键字（例如，["warning", "robot"]）。最多 5 个。
priority	integer	否	消息优先级：1=min，2=low，3=default，4=high，5=max。
click	string	否	单击通知时要打开的 URL。
actions	array	否	操作按钮（view、http、broadcast）。最多 3 个。
attachment	object	否	附件的 URL 和名称。
email	string	否	要将通知转发到的电子邮件地址。
delay	string	否	延迟发送（例如，30m、1h、tomorrow）。
cache	string	否	缓存持续时间（例如，10m、1h、1d）。
firebase	string	否	要转发到的 Firebase Cloud Messaging (FCM) 主题。
id	string	否	消息的唯一 ID。
expires	string	否	消息过期时间（例如，10m、1h、1d）。
markdown	boolean	否	设置为 true 以启用消息中的 markdown 格式。
baseUrl	string	否	覆盖此请求的默认 ntfy 服务器 URL。

用法示例：

// 基本通知
{
  "topic": "alerts",
  "message": "The task has completed successfully."
}

// 高级通知
{
  "topic": "alerts",
  "title": "System Alert",
  "message": "CPU usage has exceeded 90% for 5 minutes.",
  "tags": ["warning", "computer"],
  "priority": 4,
  "click": "https://server-dashboard.example.com",
  "actions": [
    {
      "id": "view",
      "label": "View Details",
      "action": "view",
      "url": "https://server-dashboard.example.com/cpu"
    },
    {
      "id": "restart",
      "label": "Restart Service",
      "action": "http",
      "url": "https://api.example.com/restart-service",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer token123"
      }
    }
  ],
  "markdown": true
}

示例响应：

{
  "success": true,
  "id": "5ZFY362156Sa",
  "topic": "ATLAS",
  "time": 1743064235,
  "expires": 1743496235,
  "message": "This is a test message from the README verification process",
  "title": "README Testing"
}

资源

直接资源

ntfy://default

• 描述： 返回服务器环境变量 (NTFY_DEFAULT_TOPIC) 中配置的默认 ntfy 主题。
• 用法： 客户端无需事先配置即可发现主要主题非常有用。
• 示例： LLM 代理可以访问此资源以在发送通知时自动使用默认主题。
• 示例响应：

  {
    "defaultTopic": "ATLAS",
    "timestamp": "2025-03-27T08:30:25.619Z",
    "requestUri": "ntfy://default",
    "requestId": "0da963d0-30e0-4dbc-bb77-4bf2dee14484"
  }
  

资源模板

ntfy://{topic}

• 描述： 返回有关特定 ntfy 主题的信息。
• 参数： topic - ntfy 主题的名称。
• 用法： 用于查询有关默认主题以外的主题的信息。
• 示例响应：

  {
    "topic": "ATLAS",
    "timestamp": "2025-03-27T08:30:30.038Z",
    "requestUri": "ntfy://ATLAS",
    "requestId": "31baf1df-278f-4fdb-860d-019f156a72b0"
  }
  

用例

1. 长时间运行的任务通知 - 在数据库备份、代码生成或数据处理等任务完成时收到通知。
2. 计划的提醒 - 为未来的事件或提醒设置延迟通知。
3. 警报系统 - 为监控系统或重要事件设置关键警报。
4. 来自 LLM 的移动通知 - 允许 LLM 直接向您的手机发送通知。
5. 多步骤流程更新 - 在复杂流程的不同阶段完成时接收更新。

用法示例

基本通知

<use_mcp_tool>
<server_name>ntfy-mcp-server</server_name>
<tool_name>send_ntfy</tool_name>
<arguments>
{
  "topic": "updates",
  "title": "Task Completed",
  "message": "Your requested data analysis has finished",
  "tags": ["check"]
}
</arguments>
</use_mcp_tool>

带有操作的丰富通知

<use_mcp_tool>
<server_name>ntfy-mcp-server</server_name>
<tool_name>send_ntfy</tool_name>
<arguments>
{
  "topic": "alerts",
  "title": "Critical Error Detected",
  "message": "The application has encountered a critical error.\n\n**Error Code**: E123\n\n**Details**: Database connection failed",
  "tags": ["warning", "skull"],
  "priority": 5,
  "actions": [
    {
      "id": "view",
      "label": "View Logs",
      "action": "view",
      "url": "https://logs.example.com"
    },
    {
      "id": "restart",
      "label": "Restart Service",
      "action": "http",
      "url": "https://api.example.com/restart",
      "method": "POST"
    }
  ],
  "markdown": true
}
</arguments>
</use_mcp_tool>

可用脚本

• npm run build：将 TypeScript 源代码编译为 dist/ 目录中的 JavaScript。
• npm run clean：删除 dist/ 目录并清理 logs/ 目录的内容。
• npm run rebuild：运行 clean，然后运行 build。
• npm run tree：在 docs/tree.md 中生成目录树表示。
• npm start：使用 Node.js 从 dist/ 目录运行已编译的服务器。
• npm run watch：跟踪组合日志文件 (logs/combined.log) 以进行实时监控。

贡献

欢迎贡献！ 请随时提交拉取请求或提出问题以改进项目。

1. Fork 存储库。
2. 创建一个功能分支 (git checkout -b feature/your-feature)。
3. 提交您的更改 (git commit -m 'Add some feature')。
4. 推送到分支 (git push origin feature/your-feature)。
5. 创建一个新的拉取请求。

对于错误和功能请求，请在存储库上创建一个问题。

开发最佳实践

• 遵循 TypeScript 最佳实践并保持强类型
• 为新功能编写测试
• 保持依赖项最新
• 遵循现有的代码风格和模式

许可证

此项目已获得 Apache-2.0 许可证的许可。 有关详细信息，请参阅 LICENSE 文件。

致谢

• ntfy.sh 提供通知服务
• 模型上下文协议 启用 LLM 到工具的连接
• 该项目的所有贡献者和用户

---

<div align="center"> 使用模型上下文协议构建 </div>