Ntfy MCP 服务器

MCP（模型上下文协议）服务器旨在与ntfy推送通知服务交互。它支持 LLM 和 AI 代理向您的设备发送通知，并提供丰富的自定义选项。

目录

• 概述

• 特征

• 快速入门

• 安装

• 配置

• 项目结构

• 工具

• 资源

• 用例

• 可用脚本

• 贡献

• 执照

概述

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

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

特征

• **MCP 服务器实现：**使用@modelcontextprotocol/sdk构建，以实现与 LLM 代理的无缝集成。

• **Ntfy 集成：**提供一个工具（ send_ntfy ）来发送通知，并支持以下内容：

  • 消息优先级（1-5 级）

  • 表情符号标签

  • 可点击的操作和按钮

  • 文件附件

  • 延迟交货

  • 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. 安装并运行：

   # Option 1: Install via npm npm install -g ntfy-mcp-server # Option 2: Clone repository and build git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-server npm install npm run build # Create .env file (optional but recommended) cp .env.example .env # Edit .env to set NTFY_DEFAULT_TOPIC # Start the server npm start

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

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

安装

选项 1：NPM 包（推荐）

1. 全局安装包：

   npm install -g ntfy-mcp-server

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

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

   npm install ntfy-mcp-server

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

选项 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文件：

MCP 客户端设置

对于 Cline VSCode 扩展

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

如果全局安装：

如果从源安装：

对于克劳德桌面应用程序

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

如果全局安装：

如果从源安装：

对于源码安装，请将 请根据您的设置调整

Ntfy 设置

1. 从ntfy.sh或应用商店在您的设备上安装 ntfy 应用

2. 在应用程序中订阅您的主题

3. 在 MCP 服务器配置中使用相同的主题

项目结构

工具

send_ntfy

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

主要论点：

示例用法：

响应示例：

资源

直接资源

ntfy://default

• **描述：**返回服务器环境变量中配置的默认 ntfy 主题（ NTFY_DEFAULT_TOPIC ）。

• **用途：**有助于客户端发现主要主题，而无需事先配置。

• 示例： 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. 多步骤流程更新- 在复杂流程的不同阶段完成时接收更新。

使用示例

基本通知

丰富的通知和操作

可用脚本

• 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 ）以进行实时监控。

贡献

欢迎贡献代码！欢迎提交 Pull Request 或 Issue，以改进项目。

1. 分叉存储库。

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 许可证。详情请参阅许可证文件。

致谢

• ntfy.sh用于提供通知服务

• 用于实现 LLM 到工具连接的模型上下文协议

• 本项目的所有贡献者和用户