NFTY MCP

NTFY MCP服务器

MCP服务器 ntfy.sh 通知、异步代理消息传递和人在循环工作流。

它为MCP客户端提供了一种简单的方法，可以将消息发布到 ntfy 主题，维护实时订阅，等待回复，而无需构建自定义消息传递层。

它的作用

此服务器在您需要时非常有用：

• 从MCP连接的代理推送通知
• 用户和代理之间的异步消息交换
• 轻量级的人工批准或回复循环 ntfy
• 一个用于长时间运行的工作流的简单通知通道

典型流程：

1. 用户或外部系统向 ntfy 主题。
2. MCP客户端读取它 wait-and-read-inbox 或 ntfy://inbox.
3. 代理人通过以下方式作出回应 send-ntfy.
4. 用户收到的响应为 ntfy 推送通知。

特性

• 发布带有可选标题、优先级、标签和附件的邮件
• 保持近乎实时交付的持久订阅
• 在不重新启动服务器的情况下切换主题
• 将最近的消息保存在内存和磁盘上
• 支持承载令牌和基本身份验证保护主题
• 与公众合作 ntfy.sh 开箱即用

安装

全局安装：

npm install -g nfty-mcp-server

或者跑过去 npx:

npx -y --yes nfty-mcp-server

快速开始

1.选择一个主题

在上创建或重用主题 ntfy.sh。公共主题易于设置，因此请选择一个唯一的名称。

2.配置您的MCP客户端

对于游标或VS代码，请将其添加到MCP设置中：

{
  "mcpServers": {
    "nfty": {
      "command": "npx",
      "args": ["-y", "--yes", "nfty-mcp-server"],
      "env": {
        "NTFY_TOPIC": "your-topic-name",
        "NTFY_BASE_URL": "https://ntfy.sh"
      }
    }
  }
}

对于Claude Desktop，将相同的服务器条目添加到 claude_desktop_config.json.

笔记：

• NTFY_TOPIC 是必需的
• --yes 保持 npx 安装在自己的缓存中，而不是污染项目目录

3.重新启动客户端

重新启动Cursor、VS Code或Claude Desktop，以便加载MCP服务器。

工具

send-ntfy

向配置的主题发布消息。

参数：

• message 必需的
• title 可选的
• priority 可选， 1 通过 5
• tags 可选的
• attachUrl 可选的

例子：

{
  "message": "Task completed successfully.",
  "title": "Task Status",
  "priority": 4
}

set-ntfy-topic

切换当前会话的活动主题。

参数：

• topic 必需的
• baseUrl 可选的

wait-and-read-inbox

等待配置主题上的新消息，并在至少有一条消息到达时返回。

参数：

• since 可选的
• sinceTime 可选的
• sinceNow 可选，默认 true

重要提示：

• 许多MCP客户端强制执行大约60秒的超时
• 如果您正在等待人工输入，客户端或调用代理应超时重试

代理聊天流的建议提示行为：

如果 wait-and-read-inbox 等待用户响应时超时，请重试，直到有新消息到达。

资源

ntfy://inbox

以JSON格式返回配置主题的最新消息。

示例形状：

{
  "topic": "your-topic",
  "baseUrl": "https://ntfy.sh",
  "messages": [
    {
      "id": "message-id",
      "time": 1234567890,
      "title": "Message Title",
      "message": "Message body",
      "priority": 3,
      "tags": ["tag1"],
      "topic": "your-topic"
    }
  ]
}

配置

数据存储

服务器将日志、缓存文件和锁文件存储在专用数据目录中，这样就不会使当前项目变得混乱。

默认位置：

• macOS/Linux： ~/.nfty-mcp-server/
• 窗户： C:\Users\\.nfty-mcp-server\

写入其中的文件包括：

• nfty-messages.json
• nfty-debug.log
• nfty-process.log
• nfty.lock

环境变量

CLI参数

您还可以直接配置服务器：

npx nfty-mcp-server --topic my-topic --base-url https://ntfy.sh --auth-token your-token

支持的参数：

• --topic
• --base-url 或 --server
• --auth-token
• --username
• --password
• --since
• --log-incoming

运作原理

1. 服务器打开对已配置主题的持久HTTP订阅。
2. 通过该实时连接接收传入消息。
3. 最近的消息缓存在内存中并持久化到磁盘。
4. MCP工具在该订阅之上公开发送、主题切换和等待/读取行为。

用例

• 异步用户代理消息传递
• 长时间运行任务的推送通知
• 人工审批循环
• 轻量级操作员警报
• 通过共享主题进行代理间协调

发展

git clone https://github.com/harshwasan/NFTY-MCP.git
cd NFTY-MCP
npm install
npm test
npm run dev

项目布局：

NFTY-MCP/
  src/server.js
  tests/server.test.js
  package.json

故障排除

未到达的消息：

• 验证 NTFY_TOPIC
• 确认主题存在并且可以访问
• 检查配置的数据目录中的调试日志

连接问题：

• 验证对已配置的网络的访问权限 NTFY_BASE_URL
• 如果主题受到保护，请验证身份验证设置

许可证

麻省理工学院