📤 ntfy-me-mcp

通过 ntfy 服务（公共或自托管且支持令牌）发送通知的简化版 Model Context Protocol (MCP) 服务器 📲

概述

ntfy-me-mcp 使 AI 助手能够通过 ntfy 服务（无论是公共的还是自托管并支持令牌）向您的设备发送实时通知。当您的 AI 完成任务、遇到错误或达到重要里程碑时，您将收到通知 - 全程无需持续监控。

该服务器包括智能功能，如自动 URL 检测以创建查看操作和智能 Markdown 格式检测，从而使 AI 助手无需额外配置即可轻松创建丰富且交互性强的通知。

可用途径：

名称	链接 / 徽章
Glama.ai
Smithery.ai

目录

• 功能
  • 即将推出...
• 快速入门 - MCP 服务器配置
  • NPM / NPX（推荐方法）
    • 最小配置
    • 完整配置
      • 选项 1：直接令牌
      • 选项 2：VS Code 输入
  • Docker
    • 与 Docker 中的 MCP 一起使用
• 安装
  • 选项 1：全局安装
  • 选项 2：使用 npx 运行
  • 选项 3：本地安装
  • 选项 4：本地构建和使用
    • 使用本地构建的服务器与 MCP
  • 选项 5：MCP 市场安装
• 配置
  • 环境变量
• 使用
  • 身份验证
  • 设置通知接收器
  • 发送通知 (ntfy_me 工具)
    • 使用自然语言
    • 消息参数
    • 操作链接
    • 表情符号简码
    • Markdown 格式化
  • 检索消息 (ntfy_me_fetch 工具)
    • 使用自然语言
    • 消息参数
    • 示例
  • 开发
    • 从源代码构建
• 许可证
• 贡献

功能

• 🚀 快速设置：使用 npx 或 docker 运行！
• 🔔 实时通知：任务完成时在手机/桌面上获取更新
• 🎨 丰富通知：支持主题、标题、优先级、表情符号标签和详细消息
• 🔍 通知检索：从您的 ntfy 主题中检索和过滤缓存的消息
• 🎯 智能操作链接：自动检测消息中的 URL 并创建查看操作
• 📄 智能 Markdown：自动检测并启用存在的 Markdown 格式
• 🔒 安全：可选的访问令牌身份验证
• 🔑 输入掩码：在 vs 配置中安全地存储您的 ntfy 令牌！
• 🌐 自托管支持：支持 ntfy.sh 和自托管 ntfy 实例

（即将推出...）

• 📨 电子邮件: 发送通知到电子邮件（需要配置 ntfy 电子邮件服务器）
• 🔗 点击链接: 自定义点击链接的能力
• 🖼️ 图片链接: 智能检测图片链接，自动将图片链接包含在消息和通知中
• 🏁 还有更多！

快速开始 - MCP 服务器配置

NPM / NPX（推荐方法）

• 需要在您的系统上安装 npm / npx。
• 对于大多数用户来说，此方法是推荐的，因为它提供了一种简单且轻量级的方式来设置服务器。

对于与 MCP 兼容的助手进行最简单的设置，请将以下内容添加到您的 MCP 配置中：

最小配置（适用于 ntfy.sh 上的公共主题）

{
  "ntfy-me-mcp": {
    "command": "npx",
    "args": ["ntfy-me-mcp"],
    "env": {
      "NTFY_TOPIC": "your-topic-name"
    }
  }
}

完整配置（适用于私有服务器或受保护的主题）

选项 1：直接在配置中使用令牌

{
  "ntfy-me-mcp": {
    "command": "npx",
    "args": ["ntfy-me-mcp"],
    "env": {
      "NTFY_TOPIC": "your-topic-name",
      "NTFY_URL": "https://your-ntfy-server.com",
      "NTFY_TOKEN": "your-auth-token" // Use if using a protected topic/server
    }
  }
}

选项 2：使用 VS Code 输入进行安全的令牌处理（推荐）

将以下内容添加到您的 VS Code settings.json 文件中：

"mcp": {
  "inputs": [
    { // Add this to your inputs array
      "type": "promptString",
      "id": "ntfy_token",
      "description": "Ntfy Token",
      "password": true
    }
  ],
  "servers": {
    // Other servers...
    "ntfy-me-mcp": {
      "command": "npx",
      "args": ["ntfy-me-mcp"],
      "env": {
        "NTFY_TOPIC": "your-topic-name",
        "NTFY_URL": "https://your-ntfy-server.com",
        "NTFY_TOKEN": "${input:ntfy_token}", // Use the input id variable for the token
        "PROTECTED_TOPIC": "true" // Prompts for token and masks it in your config
      }
    }
  }
}

通过这种设置，VS Code 将在启动服务器时提示您输入令牌，并且在输入时会隐藏令牌。

Docker

使用 Docker 中的 MCP

• 需要在您的系统上安装 Docker。
• 此方法适用于在容器化环境中运行服务器。
• 您可以使用 Docker Hub 或 GitHub Container Registry 上提供的官方 Docker 镜像。

Docker 镜像：

• gitmotion/ntfy-me-mcp:latest（Docker Hub）
• ghcr.io/gitmotion/ntfy-me-mcp:latest（GitHub Container Registry）

在您的 MCP 配置中（例如，VS Code settings.json）：

"mcp": {
  "servers": {
    "ntfy-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "NTFY_TOPIC",
        "-e",
        "NTFY_URL",
        "-e",
        "NTFY_TOKEN",
        "-e",
        "PROTECTED_TOPIC",         
        "gitmotion/ntfy-me-mcp", // OR use ghcr.io/gitmotion/ntfy-me-mcp:latest
      ],
      "env": {
        "NTFY_TOPIC": "your-topic-name",
        "NTFY_URL": "https://your-ntfy-server.com",
        "NTFY_TOKEN": "${input:ntfy_token}",
        "PROTECTED_TOPIC": "true"
      }
    }
  }
}

安装

如果您需要直接安装并运行服务器（作为上述 MCP 配置的替代方案）：

选项 1：全局安装

npm install -g ntfy-me-mcp

选项 2：使用 npx 运行

npx ntfy-me-mcp

选项 3：本地安装

# Clone the repository
git clone https://github.com/gitmotion/ntfy-me-mcp.git
cd ntfy-me-mcp

# Install dependencies
npm install

# Copy the example environment file and configure it
cp .env.example .env
# Edit .env with your preferred editor and update the variables
# nano .env  # or use your preferred editor

# Build the project
npm run build

# Start the server
npm start

选项 4：使用 node 命令构建并在本地运行

如果您正在开发或自定义服务器，可能希望直接使用 node 运行它：

# Clone the repository
git clone https://github.com/gitmotion/ntfy-me-mcp.git
cd ntfy-me-mcp

# Install dependencies
npm install

# Copy the example environment file and configure it
cp .env.example .env
# Edit the .env file to set your NTFY_TOPIC and other optional settings
# nano .env  # or use your preferred editor

# Build the project
npm run build

# Run using node directly
npm start

使用本地构建的服务器与 MCP

当配置您的 MCP 以使用本地构建的版本时，请指定 node 命令和构建后的 index.js 文件路径：

{
  "ntfy-me": {
    "command": "node",
    "args": ["/path/to/ntfy-mcp/build/index.js"],
    "env": {
      "NTFY_TOPIC": "your-topic-name",
      //"NTFY_URL": "https://your-ntfy-server.com", // Use if using a self-hosted server
      //"NTFY_TOKEN": "your-auth-token" // Use if using a protected topic/server
    }
  }
}

请记得在 args 数组中使用 build/index.js 文件的绝对路径。

选项 5：MCP 市场安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 ntfy-me-mcp：

npx -y @smithery/cli install @gitmotion/ntfy-me-mcp --client claude

配置

环境变量

通过复制提供的示例，在项目目录中创建一个 .env 文件：

# Copy the example file
cp .env.example .env

# Edit the file with your preferred editor
nano .env  # or vim, code, etc.

您的 .env 文件应包含这些变量：

# Required
NTFY_TOPIC=your-topic-name

# Optional - Configure these if using a private/protected ntfy server
# NTFY_URL=https://ntfy.sh  # Default is ntfy.sh, change to your self-hosted ntfy server URL if needed
                            # Include port if needed, e.g., https://your-ntfy-server.com:8443
# NTFY_TOKEN=your-access-token  # Required for authentication with protected topics/servers
# PROTECTED_TOPIC=false  # Set to "true" if your topic requires authentication (helps prevent auth errors)

注意：PROTECTED_TOPIC 标志帮助应用程序确定是否需要对您的主题进行身份验证。当设置为 "true" 且未提供令牌时，系统将提示您输入令牌。这可以防止受保护主题的身份验证失败。

使用

身份验证

该服务器支持经过身份验证和未经身份验证的 ntfy 端点：

• 公开主题：在使用 ntfy.sh 或其他公共服务器上的公开主题时，不需要进行身份验证。
• 受保护的主题：对于受保护的主题或私有服务器，你需要提供一个访问令牌。

如果需要身份验证但未提供，你将收到一条清晰的错误消息，解释如何添加你的令牌。

设置通知接收器

1. 在你的设备上安装 ntfy 应用
2. 订阅你选择的主题（与你的 NTFY_TOPIC 设置相同）

发送通知 (ntfy_me 工具)

本节涵盖了使用 ntfy_me 工具发送通知的所有相关功能。

使用自然语言

当你与 AI 助手合作时，你可以使用像这样的自然短语：

"Send me a notification when the build is complete"
"Notify me when the task is done"
"Alert me after generating the code"
"Message me when the process finishes"
"Send an alert with high priority"

消息参数

该工具接受以下参数：

示例：

{
  taskTitle: "Code Generation Complete",
  taskSummary: "Your React component has been created successfully with proper TypeScript typing.",
  priority: "high",
  tags: ["check", "code", "react"]
}

这将发送一个高优先级的通知，并带有复选标记表情符号。

动作链接

你可以使用 actions 参数向通知中添加可点击的动作按钮，或者让服务器自动检测消息中的 URL。

自动 URL 检测

当消息正文中存在 URL 时，服务器会自动从检测到的第一个 URL 创建最多 3 个查看动作（ntfy 的最大限制）。这样可以轻松地包含可点击链接而无需手动指定动作数组。

例如，这条消息：

{
  taskTitle: "Build Complete",
  taskSummary: "Your PR has been merged! View the changes at https://github.com/org/repo/pull/123 or check the deployment at https://staging.app.com"
}

将为两个 URL 自动生成查看动作，使它们在通知中易于点击。

手动配置动作

为了获得更多控制，你可以手动指定动作：

带动作链接的示例：

{
  taskTitle: "Pull Request Review",
  taskSummary: "Your code has been reviewed and is ready for final checks",
  priority: "high",
  tags: ["check", "code"],
  actions: [
    {
      action: "view",
      label: "View PR",
      url: "https://github.com/org/repo/pull/123"
    },
    {
      action: "view",
      label: "View Changes",
      url: "https://github.com/org/repo/pull/123/files",
      clear: true
    }
  ]
}

Emoji 短代码

你可以在标签中使用 emoji 短代码作为视觉指示符：

• warning → ⚠️
• check → ✅
• rocket → 🚀
• tada → 🎉

查看 支持的完整 emoji 短代码列表。

Markdown 格式

你的通知支持丰富的 markdown 格式，并具有智能检测功能！当你在 taskSummary 中包含 markdown 语法时，服务器会自动检测并启用 markdown 解析 - 无需显式设置 markdown: true。

自动检测

服务器检查常见的 markdown 模式，如：

• 标题 (#, ## 等)
• 列表 (-, *, 数字)
• 代码块 (```)
• 链接 (文本)
• 加粗/斜体 (文本, 文本)

当检测到这些模式时，消息会自动启用 markdown 解析。

手动覆盖

虽然大多数情况下自动检测可以正常工作，但你仍然可以显式控制 markdown 解析：

{
  taskTitle: "Task Complete",
  taskSummary: "Regular plain text message",
  markdown: false  // Force disable markdown parsing
}

获取消息 (ntfy_me_fetch 工具)

本节涵盖了使用 ntfy_me_fetch 工具获取和过滤消息的所有功能。

使用自然语言

AI 助手能够理解多种请求获取消息的方式：

"Show me my recent notifications"
"Get messages from the last hour"
"Find notifications with title 'Build Complete'"
"Search for messages with the test_tube tag"
"Show notifications from the updates topic from the last 24hr"
"Check my latest alerts"

消息参数

该工具接受以下参数：

示例

1. 获取最近的消息

{
  since: "30m"  // Get messages from last 30 minutes
}

1. 按标题和优先级筛选

{
  messageTitle: "Build Complete",
  priorities: "high",
  since: "1d"
}

1. 使用标签搜索不同主题

{
  ntfyTopic: "updates",
  tags: ["error", "warning"],
  since: "all"
}

1. 查找特定消息

{
  messageId: "xxxxXXXXxxxx"
}

返回的消息包含完整详情，包括：

• 消息 ID 和时间戳
• 主题和标题
• 内容和优先级
• 标签和附件
• 操作链接和过期时间

注意：消息历史记录的可用性取决于你的 ntfy 服务器缓存设置。公共 ntfy.sh 服务器通常缓存消息 12 小时。

开发

从源码构建

git clone https://github.com/gitmotion/ntfy-me-mcp.git
cd ntfy-me-mcp
npm install
npm run build

许可证

本项目根据 GNU 通用公共许可证 v3.0 授权 - 详情请参阅 LICENSE 文件。

贡献

欢迎贡献！请随时提交 Pull Request。

由 gitmotion 用❤️制作