Ntfy MCP Server

🚀 Ntfy-MCP 服務器

Ntfy-MCP 服務器是一個基於 Node.js 的實用工具，藉助 Model Context Protocol (MCP) 協議，它能將語言模型與 Ntfy.sh 通知服務相連接。該項目的核心價值在於，允許大語言模型（LLM）直接向手機或其他設備發送通知，為信息傳遞提供了新的途徑。

🚀 快速開始

安裝依賴

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

配置環境變量

編輯項目根目錄下的 .env 文件：

NFTY_API_KEY=your_api_key_here # 必填，你的 Ntfy API 密鑰
PORT=3001                    # 可選，默認為 3001
DEBUG=true                   # 可選，啟用調試模式

✨ 主要特性

核心功能

• 協議支持：實現 MCP 協議，讓 LLM 可通過此工具調用 API 發送通知。
• Ntfy 集成：全面支持 Ntfy 的各類特性，涵蓋消息標題和內容、標籤（#tag）、優先級設置、延遲發送以及自定義動作等。
• 多主題支持：可通過不同主題實現多樣化的通知邏輯。

💻 使用示例

基礎用法

在 MCP 客戶端中，發送基本的 Ntfy 通知：

<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 客戶端中，發送帶有自定義動作的 Ntfy 通知：

<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 通知的 JSON 示例：

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

貢獻指南

1. 代碼倉庫：GitHub 倉庫
2. 問題反饋：通過 GitHub 提交 Issues 或 Pull Request。
3. 開發規範：
   • 遵循項目現有的代碼風格和結構。
   • 新功能添加需配套單元測試。

開發最佳實踐

• 日誌記錄：在 main.ts 中啟用調試模式，便於排查問題。
• 依賴管理：定期檢查並更新包依賴，確保兼容性。
• 模塊劃分：按照功能模塊劃分代碼，保持項目結構清晰。

🔧 技術細節

Ntfy-MCP 服務器基於 Node.js 構建，通過實現 MCP 協議，將 LLM 與 Ntfy 服務連接起來。它的代碼結構清晰，按照功能模塊進行劃分，包括工具模塊和第三方服務適配器。在使用時，通過配置環境變量和調用相應的工具，可實現通知的發送。同時，項目還提供了多種腳本，方便在開發和生產環境中使用。

📄 許可證

本項目基於 MIT 協議開源，具體許可信息詳見 LICENSE 文件。

如需瞭解更多細節，請參考項目的 Wiki 頁面 或聯繫維護者。