Ntfy MCP 服务器
MCP（模型上下文协议）服务器旨在与ntfy推送通知服务交互。它支持 LLM 和 AI 代理向您的设备发送通知，并提供丰富的自定义选项。
目录
概述
该服务器实现了模型上下文协议 (MCP)，从而实现了 LLM 与外部系统之间的标准化通信。具体来说，它提供了 ntfy 推送通知服务的接口。
Ntfy是一款基于 HTTP 的简单发布/订阅通知服务，允许您通过简单的 HTTP 请求将通知发送到您的手机或桌面。借助此 MCP 服务器，像 Claude 这样的 LLM 代理可以通过 ntfy 向您发送通知，而无需直接访问 HTTP。
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐
│ LLM Agent │ ────▶│ Ntfy MCP │ ────▶│ Ntfy │ ────▶│ Your │
│ (Claude) │ │ Server │ │ Service │ │ Devices │
└───────────┘ └───────────┘ └───────────┘ └─────────┘
特征
- **MCP 服务器实现：**使用
@modelcontextprotocol/sdk构建，以实现与 LLM 代理的无缝集成。 - **Ntfy 集成：**提供一个工具（
send_ntfy ）来发送通知，并支持以下内容：- 消息优先级（1-5 级）
- 表情符号标签
- 可点击的操作和按钮
- 文件附件
- 延迟交货
- Markdown 格式
- **资源公开：**将配置的默认 ntfy 主题作为 MCP 资源公开。
- **TypeScript：**具有全面类型定义的现代、类型安全的代码库。
- **结构化日志记录：**使用
winston和winston-daily-rotate-file获取详细且可轮换的日志。 - **配置管理：**使用
dotenv轻松进行基于环境的配置。 - **实用程序脚本：**包括用于清理构建工件和生成目录结构文档的脚本。
- **错误处理和安全：**实现强大的错误处理、输入清理（
sanitize-html ）和安全过滤器（ xss-filters ）。
快速入门
- 先决条件：
- Node.js（v16+）
- npm 或 yarn
- 与 MCP 兼容的客户端（Claude Desktop、Cline 等）
- 安装并运行：
# 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
- **添加到 MCP 客户端设置：**将服务器添加到您的 MCP 客户端设置文件（请参阅配置）
- **使用工具：**连接后，您可以使用
send_ntfy工具发送通知。
安装
选项 1：NPM 包（推荐）
- 全局安装包：
npm install -g ntfy-mcp-server
- 或者在您的项目中本地安装：
npm install ntfy-mcp-server
选项 2：从源头
- 克隆存储库：
git clone https://github.com/cyanheads/ntfy-mcp-server.git
cd ntfy-mcp-server
- 安装依赖项：
- 构建项目：
配置
环境变量
根据.env.example在项目根目录中创建一个.env文件：
# Ntfy Configuration
NTFY_BASE_URL=https://ntfy.sh # Optional: Base URL of your ntfy instance
NTFY_DEFAULT_TOPIC=your_default_topic # Optional: Default topic if none specified in requests
# Application Configuration
LOG_LEVEL=info # Optional: Logging level (debug, info, warn, error)
NODE_ENV=development # Optional: Environment (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 配置文件（通常位于 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 设置
- 从ntfy.sh或应用商店在您的设备上安装 ntfy 应用
- 在应用程序中订阅您的主题
- 在 MCP 服务器配置中使用相同的主题
项目结构
.
├── .env.example # Example environment variables
├── .gitignore # Git ignore patterns
├── LICENSE # Project license (Apache-2.0)
├── package.json # Project metadata and dependencies
├── tsconfig.json # TypeScript compiler configuration
├── docs/
│ └── tree.md # Auto-generated directory structure
├── logs/ # Runtime logs (created automatically)
├── scripts/ # Utility scripts
│ ├── clean.ts # Cleans build artifacts and logs
│ └── tree.ts # Generates the docs/tree.md file
└── src/ # Source code
├── index.ts # Main server entry point
├── config/ # Configuration loading
├── mcp-server/ # MCP server logic, tools, and resources
│ ├── resources/ # MCP resource implementations
│ ├── tools/ # MCP tool implementations
│ └── utils/ # MCP-specific utilities
├── services/ # External service integrations (ntfy)
├── types-global/ # Global type definitions
└── utils/ # General utility functions
工具
send_ntfy
通过 ntfy 服务发送通知消息。
主要论点：
| 范围 | 类型 | 必需的 | 描述 |
|---|
topic | 细绳 | 是的 | 要发布的 ntfy 主题。 |
message | 细绳 | 是的 | 通知的主要内容（最大4096字节）。 |
title | 细绳 | 不 | 通知标题（最多 250 个字节）。 |
tags | 细绳[] | 不 | 用于分类的表情符号或关键词（例如， ["warning", "robot"] ）。最多 5 个。 |
priority | 整数 | 不 | 消息优先级：1=最小，2=低，3=默认，4=高，5=最大。 |
click | 细绳 | 不 | 单击通知时打开的 URL。 |
actions | 大批 | 不 | 操作按钮（查看、http、广播）。最多 3 个。 |
attachment | 目的 | 不 | 附件的 URL 和名称。 |
email | 细绳 | 不 | 转发通知的电子邮件地址。 |
delay | 细绳 | 不 | 延迟递送（例如， 30m 、 1h 、 tomorrow ）。 |
cache | 细绳 | 不 | 缓存时长（例如， 10m 、 1h 、 1d ）。 |
firebase | 细绳 | 不 | 要转发到的 Firebase Cloud Messaging (FCM) 主题。 |
id | 细绳 | 不 | 消息的唯一 ID。 |
expires | 细绳 | 不 | 消息过期时间（例如， 10m 、 1h 、 1d ）。 |
markdown | 布尔值 | 不 | 设置为true以在消息中启用 markdown 格式。 |
baseUrl | 细绳 | 不 | 覆盖此请求的默认 ntfy 服务器 URL。 |
示例用法：
// Basic notification
{
"topic": "alerts",
"message": "The task has completed successfully."
}
// Advanced notification
{
"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 主题（
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"
}
用例
- 长时间运行的任务通知- 当数据库备份、代码生成或数据处理等任务完成时收到通知。
- 预定提醒- 为未来事件或提醒设置延迟通知。
- 警报系统- 为监控系统或重要事件设置关键警报。
- 来自 LLM 的移动通知- 允许 LLM 将通知直接发送到您的手机。
- 多步骤流程更新- 在复杂流程的不同阶段完成时接收更新。
使用示例
基本通知
<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 ）以进行实时监控。
贡献
欢迎贡献代码！欢迎提交 Pull Request 或 Issue，以改进项目。
- 分叉存储库。
- 创建一个功能分支（
git checkout -b feature/your-feature ）。 - 提交您的更改（
git commit -m 'Add some feature' ）。 - 推送到分支（
git push origin feature/your-feature ）。 - 创建一个新的拉取请求。
对于错误和功能请求，请在存储库上创建问题。
开发最佳实践
- 遵循 TypeScript 最佳实践并保持强类型
- 为新功能编写测试
- 保持依赖项最新
- 遵循现有的代码风格和模式
执照
本项目遵循 Apache-2.0 许可证。详情请参阅许可证文件。
致谢