NTFY

You can run an MCP server that enables bidirectional chat with AI agents through ntfy.sh. This server maintains real-time subscriptions, publishes messages to a topic, and lets clients wait for responses, creating a flexible push-notification based workflow.

How to use

Install and run the MCP server locally, then configure your MCP client to connect through the server. Your client can publish messages to a ntfy topic, wait for replies, and continue the conversation at your own pace. Use this pattern to build asynchronous chat flows with AI agents where responses arrive as push notifications and the agent can wait for your next message.

How to install

# Prerequisites
node >= 18
npm >= 6

# Option 1: install globally (recommended for quick starts)
npm install -g nfty-mcp-server

# Run the MCP server (will prompt for topic and base URL if not specified via env)
nfty-mcp-server

# Option 2: run via npx without global install
npx nfty-mcp-server

The server uses a ntfy topic you specify to publish and receive messages. Ensure you have a topic created on ntfy.sh and that you configure your client to use that topic.

## Configuration and usage notes

The MCP server stores data and logs in a dedicated directory to keep your project clean. You can customize the data location with an environment variable. When starting, the server creates a persistent subscription to the chosen ntfy topic to deliver messages in real time.

## Configuration details

Environment variables control how the server connects and stores data. Use the following variables in your environment or in your MCP client configuration file.

## Tools and interactions

Available actions you can perform via the MCP client include sending messages, waiting for inbound messages, and changing the active topic during a session.

## Examples of common workflows

- Send a message to the configured ntfy topic and wait for a reply. - The AI agent can retry the wait operation if it times out, allowing long-running conversations.

## Troubleshooting

If messages don’t arrive, verify the topic is correct and that the ntfy subscription is active. Check debug logs in the data directory and confirm network access to ntfy.sh. If authentication is required, ensure your tokens and credentials are configured in the client and server environment.

## Notes

This server is designed to work out of the box with public ntfy topics but supports protected topics via authentication tokens. The chat workflow can be long-running, with retries handled by the AI agent as needed.

## Security considerations

Use bearer tokens or basic authentication for protected topics and keep credentials secure in your environment or configuration management system.

## Appendix: MCP server configuration

{ "mcpServers": { "nfty": { "type": "stdio", "command": "npx", "args": ["-y", "--yes", "nfty-mcp-server"], "env": { "NTFY_TOPIC": "your-topic-name", "NTFY_BASE_URL": "https://ntfy.sh" } } }, "envVars": { "NTFY_TOPIC": { "description": "Topic to send/receive messages (required)", "required": true, "example": "your-topic-name" }, "NTFY_BASE_URL": { "description": "ntfy server URL", "required": false, "example": "https://ntfy.sh" } } }

Notes:
- This config uses a local run command via npx to start the MCP server. - Adjust the topic and base URL as needed for your environment.

About the server data and logs

Data files, caches, and logs are stored in a dedicated directory to avoid cluttering your project. You can override the location with an environment variable.

Available tools

send-ntfy

Publish a message to the configured ntfy topic with optional title, priority, tags, and attachments.

set-ntfy-topic

Change the ntfy topic for the current session without restarting the server.

wait-and-read-inbox

Wait for new messages on the configured topic and return when a new message arrives, using the existing subscription.