NTFY MCP Server

MCP server for ntfy.sh notifications, asynchronous agent messaging, and human-in-the-loop workflows.

It provides a simple way for an MCP client to publish messages to an ntfy topic, maintain a live subscription, and wait for replies without building a custom messaging layer.

What It Does

This server is useful when you need:

• push notifications from an MCP-connected agent

• asynchronous message exchange between a user and an agent

• a lightweight human approval or reply loop over ntfy

• a simple notification channel for long-running workflows

Typical flow:

1. A user or external system publishes a message to an ntfy topic.

2. The MCP client reads it through wait-and-read-inbox or ntfy://inbox.

3. The agent responds through send-ntfy.

4. The user receives the response as an ntfy push notification.

Features

• publish messages with optional title, priority, tags, and attachments

• maintain a persistent subscription for near real-time delivery

• switch topics without restarting the server

• keep recent messages in memory and on disk

• support bearer-token and basic-auth protected topics

• work with public ntfy.sh out of the box

Installation

Install globally:

npm install -g nfty-mcp-server

Or run through npx:

npx -y --yes nfty-mcp-server

Quick Start

1. Choose a topic

Create or reuse a topic on ntfy.sh. Public topics are easy to set up, so pick a unique name.

2. Configure your MCP client

For Cursor or VS Code, add this to your MCP settings:

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

For Claude Desktop, add the same server entry to claude_desktop_config.json.

Notes:

• NTFY_TOPIC is required

• --yes keeps npx installs in its own cache instead of polluting a project directory

3. Restart the client

Restart Cursor, VS Code, or Claude Desktop so the MCP server is loaded.

Tools

send-ntfy

Publishes a message to the configured topic.

Parameters:

• message required

• title optional

• priority optional, 1 through 5

• tags optional

• attachUrl optional

Example:

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

set-ntfy-topic

Switches the active topic for the current session.

Parameters:

• topic required

• baseUrl optional

wait-and-read-inbox

Waits for new messages on the configured topic and returns when at least one arrives.

Parameters:

• since optional

• sinceTime optional

• sinceNow optional, default true

Important:

• many MCP clients impose an approximately 60-second timeout

• if you are waiting on human input, the client or calling agent should retry on timeout

Recommended prompt behavior for agent chat flows:

If wait-and-read-inbox times out while waiting for a user response, retry until a new message arrives.

Resources

ntfy://inbox

Returns recent messages for the configured topic as JSON.

Example shape:

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

Configuration

Data Storage

The server stores logs, cache files, and lock files in a dedicated data directory so it does not clutter the current project.

Default location:

• macOS / Linux: ~/.nfty-mcp-server/

• Windows: C:\Users\<user>\.nfty-mcp-server\

Files written there include:

• nfty-messages.json

• nfty-debug.log

• nfty-process.log

• nfty.lock

Environment Variables

CLI Arguments

You can also configure the server directly:

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

Supported arguments:

• --topic

• --base-url or --server

• --auth-token

• --username

• --password

• --since

• --log-incoming

How It Works

1. The server opens a persistent HTTP subscription to the configured topic.

2. Incoming messages are received through that live connection.

3. Recent messages are cached in memory and persisted to disk.

4. MCP tools expose send, topic-switching, and wait/read behavior on top of that subscription.

Use Cases

• asynchronous user-agent messaging

• push notifications for long-running tasks

• human approval loops

• lightweight operator alerts

• agent-to-agent coordination through a shared topic

Development

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

Project layout:

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

Troubleshooting

Messages not arriving:

• verify NTFY_TOPIC

• confirm the topic exists and is reachable

• inspect the debug log in the configured data directory

Connection problems:

• verify network access to the configured NTFY_BASE_URL

• verify authentication settings if the topic is protected

License

MIT