Skip to main content
Glama
ntfy-mcp-server

ntfy-mcp-server

by cyanheads

Ntfy MCP 服务器

TypeScript 模型上下文协议 版本 执照 地位 GitHub

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

目录

Related MCP server: ntfy-me-mcp

概述

该服务器实现了模型上下文协议 (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 )。

快速入门

  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文件:

# 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 设置

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

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

  3. 在 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"
    }

用例

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

贡献

欢迎贡献代码!欢迎提交 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 许可证。详情请参阅许可证文件。

致谢


Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A streamlined MCP server that enables AI assistants to send real-time notifications to your devices through the ntfy service, allowing you to receive alerts when tasks complete or important events occur.
      2
      190 npm
      77
      GPL 3.0
    • A
      license
      C
      quality
      D
      maintenance
      MCP server for sending notifications to ntfy.sh or self-hosted ntfy instances.
      2
      13 npm
      MIT