JinDaGe - ntfy-mcp-server MCP Details

article

README

🚀 Ntfy-MCP 服务器

Ntfy-MCP 服务器是一款基于 Node.js 的实用工具，借助 Model Context Protocol (MCP) 协议，它能将语言模型与 Ntfy.sh 通知服务紧密相连。该项目为大语言模型（LLM）提供了直接向手机或其他设备发送通知的能力，极大地拓展了通知的应用场景。

🚀 快速开始

Ntfy-MCP 服务器可让 LLM 轻松通过 MCP 协议与 Ntfy.sh 服务交互，实现通知的发送。你只需按照以下步骤进行安装和配置，即可快速开启通知服务。

✨ 主要特性

核心功能

协议支持：实现了 MCP 协议，LLM 可通过该工具调用 API 来发送通知。
Ntfy 集成：全面支持 Ntfy 的各项特性，涵盖消息标题和内容设置、标签（#tag）添加、优先级调整、延迟发送以及自定义动作等。
多主题支持：支持使用不同主题，以实现多样化的通知逻辑。

📦 安装指南

安装依赖

在项目中执行以下命令来安装所需依赖：

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>

高级用法

在 MCP 客户端中，使用以下代码发送带有自定义动作的通知：

<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>

📚 详细文档

工具示例 - 发送 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               # 应用入口文件

目录结构说明

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

🔧 技术细节

使用场景

示例 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 客户端中，使用以下代码进行 Web 推送：

<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

开发最佳实践

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

📄 许可证

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

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

ntfy-mcp-server