STARWARCLOUD STARWAR.AI
返回市场
通知-MCP服务器

通知-MCP服务器

作者：cyanheads14 星标更新：2025-07-22
安装使用来源：spider==github.com

项目介绍

Ntfy MCP Server

TypeScript Model Context Protocol Version License Status GitHub

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

目录

概述

此服务器实现了模型上下文协议（MCP），使LLMs和外部系统之间的通信标准化。具体来说，它提供了一个与ntfy推送通知服务交互的接口。

Ntfy是一个基于HTTP的pub-sub通知服务，允许您通过简单的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）。

快速开始

  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文件，基于.env.example：

# 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桌面应用

将以下配置添加到您的Claude桌面配置文件中（通常位于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.sh或应用商店安装ntfy应用。
  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服务发送通知消息。

关键参数：

参数名类型是否必需描述
topicstring是要发布的ntfy主题。
messagestring是通知的主要内容（最大4096字节）。
titlestring否通知标题（最大250字节）。
tagsstring[]否分类用的表情符号或关键词（例如，["警告", "机器人"]）。最多5个。
priorityinteger否消息优先级：1=最小，2=低，3=默认，4=高，5=最大。
clickstring否点击通知时打开的URL。
actionsarray否动作按钮（查看，http，广播）。最多3个。
attachmentobject否附件的URL和名称。
emailstring否转发通知的电子邮件地址。
delaystring否延迟发送（例如，30m，1h，明天）。
cachestring否缓存持续时间（例如，10m，1h，1d）。
firebasestring否转发到的Firebase云消息（FCM）主题。
idstring否消息的唯一ID。
expiresstring否消息过期时间（例如，10m，1h，1d）。
markdownboolean否设置为true以启用消息中的Markdown格式化。
baseUrlstring否覆盖此请求的默认ntfy服务器URL。

示例用法：

// 基本通知
{
  "topic": "警报",
  "message": "任务已成功完成。"
}

// 高级通知
{
  "topic": "警报",
  "title": "系统警报",
  "message": "CPU使用率超过90%，持续5分钟。",
  "tags": ["警告", "计算机"],
  "priority": 4,
  "click": "https://server-dashboard.example.com",
  "actions": [
    {
      "id": "查看",
      "label": "查看详情",
      "action": "查看",
      "url": "https://server-dashboard.example.com/cpu"
    },
    {
      "id": "重启",
      "label": "重启服务",
      "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": "这是来自README验证过程的测试消息",
  "title": "README测试"
}

资源

直接资源

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

使用示例

基本通知

<use_mcp_tool>
<server_name>ntfy-mcp-server</server_name>
<tool_name>send_ntfy</tool_name>
<arguments>
{
  "topic": "更新",
  "title": "任务完成",
  "message": "您请求的数据分析已完成",
  "tags": ["检查"]
}
</arguments>
</use_mcp_tool>

富通知带动作

<use_mcp_tool>
<server_name>ntfy-mcp-server</server_name>
<tool_name>send_ntfy</tool_name>
<arguments>
{
  "topic": "警报",
  "title": "检测到严重错误",
  "message": "应用程序遇到了严重错误。\n\n**错误代码**：E123\n\n**详情**：数据库连接失败",
  "tags": ["警告", "骷髅"],
  "priority": 5,
  "actions": [
    {
      "id": "查看",
      "label": "查看日志",
      "action": "查看",
      "url": "https://logs.example.com"
    },
    {
      "id": "重启",
      "label": "重启服务",
      "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. 分叉仓库。
  2. 创建功能分支（git checkout -b feature/your-feature）。
  3. 提交更改（git commit -m '添加某些功能'）。
  4. 推送到