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
本地安装后，您可以通过 npx 或从节点运行它。

选项 2：从源头

克隆存储库：
git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-server
安装依赖项：
npm install
构建项目：
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 设置

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

致谢

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

Integrations

Ntfy MCP 服务器

目录

概述

特征

快速入门

安装

选项 1：NPM 包（推荐）

选项 2：从源头

配置

环境变量

MCP 客户端设置

对于 Cline VSCode 扩展

如果全局安装：

如果从源安装：

对于克劳德桌面应用程序

如果全局安装：

如果从源安装：

Ntfy 设置

项目结构

工具

send_ntfy

主要论点：

示例用法：

响应示例：

资源

直接资源

ntfy://default

资源模板

ntfy://{topic}

用例

使用示例

基本通知

丰富的通知和操作

可用脚本

贡献

开发最佳实践

执照

致谢

Appeared in Searches

`send_ntfy`

`ntfy://default`

`ntfy://{topic}`