Ntfy-MCP 服务器

文档

项目概述

Ntfy-MCP 服务器是一个基于 Node.js 的工具，旨在通过 Model Context Protocol (MCP) 连接语言模型与 Ntfy.sh 通知服务。这个项目允许 LLM（大语言模型）直接发送通知到手机或其他设备。

功能模块

核心功能

• 协议支持：实现 MCP 协议，使 LLM 能够通过工具调用 API 发送通知。
• Ntfy 集成：支持所有 Ntfy 特性，包括但不限于：
  • 消息标题和内容
  • 标签（#tag）
  • 优先级设置
  • 延迟发送
  • 自定义动作
• 多主题支持：允许通过不同主题实现不同的通知逻辑。

工具示例

发送 Ntfy 通知

{
  "tool_name": "send_ntfy",
  "args": {
    "topic": "string", // 必填，Ntfy 主题名称
    "title?: string, // 可选，通知标题
    "message?: string, // 可选，通知内容
    "tags?: string[], // 可选，通知标签
    "priority?: number, // 可选，优先级（1-5）
    "schedule?: string, // 可选，ISO 8601 格式的时间字符串，表示延迟发送时间
    "actions?: {
      id: string,
      label: string,
      action: "view" | "http",
      url: string,
      method?: "GET" | "POST" | "PUT" | "DELETE",
      body?: string
    }[]
  }
}

目录结构

src/
├── tools/                 # 工具模块目录
│   └── send_ntfy.ts      # 发送 Ntfy 通知工具实现
├── services/             # 第三方服务适配器
│   └── ntfy.ts          # Ntfy 服务适配器
└── main.ts               # 应用入口文件

安装与配置

安装依赖

npm install @model-context-protocol/core ntfy axios

配置环境变量

编辑项目根目录下的 .env 文件：

NFTY_API_KEY=your_api_key_here # 必填，你的 Ntfy API 密钥
PORT=3001                    # 可选，默认为 3001
DEBUG=true                   # 可选，启用调试模式

使用示例

基本用法

在 MCP 客户端中：

<use_mcp_tool>
  <server_name>ntfy-mcp-server</server_name>
  <tool_name>send_ntfy</tool_name>
  <arguments>
    {
      "topic": "my-topic",
      "message": "这是一个测试通知。"
    }
  </arguments>
</use_mcp_tool>

带自定义动作的用法

<use_mcp_tool>
  <server_name>ntfy-mcp-server</server_name>
  <tool_name>send_ntfy</tool_name>
  <arguments>
    {
      "topic": "my-topic",
      "title": "系统通知",
      "message": "点击以下链接查看更多信息。",
      "tags": ["system", "notification"],
      "actions": [
        {
          "id": "click_me",
          "label": "查看详情",
          "action": "http",
          "url": "https://example.com/notification/123"
        }
      ]
    }
  </arguments>
</use_mcp_tool>

目录结构说明

.
├── src/
│   ├── tools/
│   │   └── send_ntfy.ts       # 发送 Ntfy 通知的具体实现
│   ├── services/
│   │   └── ntfy.ts           # 对外提供 Ntfy 服务接口的适配器
│   └── main.ts               # 应用启动文件
├── .env                       # 环境变量配置文件
└── package.json              # 项目依赖和脚本信息

项目特点

• 简单易用：通过 MCP 协议快速实现 LLM 驱动的通知发送功能。
• 高度可定制：支持自定义动作、优先级和延迟时间，满足不同场景需求。
• 稳定可靠：基于 Node.js 和 Ntfy 官方 SDK 实现，保证服务的稳定性。

使用场景

示例 1：手机通知

在 MCP 客户端中：

<use_mcp_tool>
  <server_name>ntfy-mcp-server</server_name>
  <tool_name>send_ntfy</tool_name>
  <arguments>
    {
      "topic": "my-phone",
      "message": "收到新邮件，请查收。"
    }
  </arguments>
</use_mcp_tool>

示例 2：Web 推送

在 MCP 客户端中：

<use_mcp_tool>
  <server_name>ntfy-mcp-server</server_name>
  <tool_name>send_ntfy</tool_name>
  <arguments>
    {
      "topic": "web-notifications",
      "title": "系统消息",
      "message": "有新的评论待处理。",
      "tags": ["system", "comment"]
    }
  </arguments>
</use_mcp_tool>

可用脚本

# 开发模式启动
npm run dev

# 生产环境构建
npm run build

# 启动构建后的应用
npm start

贡献指南

1. 代码仓库：GitHub 仓库
2. 问题反馈：通过 GitHub 提交 Issues 或 Pull Request。
3. 开发规范：
   • 遵循项目现有的代码风格和结构。
   • 新功能添加需配套单元测试。

开发最佳实践

• 日志记录：在 main.ts 中启用调试模式，便于排查问题。
• 依赖管理：定期检查并更新包依赖，确保兼容性。
• 模块划分：按照功能模块划分代码，保持项目结构清晰。

许可证

本项目基于 MIT 协议开源，具体许可信息详见 LICENSE 文件。

如需了解更多细节，请参考项目的 Wiki 页面 或联系维护者。