Simple ntfy MCP Server

Send push notifications to your mobile device via ntfy.sh from Claude Desktop or any agent supporting the Model Context Protocol (MCP).

What is This?

This MCP (Model Context Protocol) server allows agents to send push notifications to your phone when tasks complete, for alerts, reminders, or any custom messages. It integrates with the free ntfy.sh notification service.

Features

• 📱 Send notifications directly from AI conversations
• 🎨 Customize with titles, priorities, and emoji tags
• 🔧 Simple configuration - no API keys needed
• 🚀 Works with any tool enabled model

Prerequisites

1. Install the ntfy app on your phone:

   • iOS: https://apps.apple.com/app/ntfy/id1625396347
   • Android: https://play.google.com/store/apps/details?id=io.heckel.ntfy

2. Subscribe to your channel:

   • Open the ntfy app
   • Tap "+" to add a subscription
   • Enter your channel name (as channel names are public, you should choose a unique name)
   • Subscribe!

3. Test your setup:

   curl -d "Hello from your computer!" ntfy.sh/yourchannel
   

   (Replace yourchannel with whatever channel name you chose)

Installation

These instructions assume you have Claude Desktop installed. To include this server in your AI coding editor or agentic solution the process will be similar. Please consult the documentation for your specific editor or solution on how to setup a custom mcp server.

Option 1: Direct Run with uvx (Recommended)

No installation needed! Just add to Claude Desktop config:

On macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ntfy": {
      "command": "uvx",
      "args": ["--from", "/path/to/ntfy-mcp", "ntfy-mcp", "--channel", "yourchannel"]
    }
  }
}

On Windows: Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "ntfy": {
      "command": "uvx",
      "args": ["--from", "C:\\path\\to\\ntfy-mcp", "ntfy-mcp", "--channel", "yourchannel"]
    }
  }
}

Replace /path/to/ntfy-mcp with the actual path and yourchannel with your desired channel name.

Alternative: Using Environment Variable

You can also set the channel using an environment variable:

{
  "mcpServers": {
    "ntfy": {
      "command": "uvx",
      "args": ["--from", "/path/to/ntfy-mcp", "ntfy-mcp"],
      "env": {
        "NTFY_CHANNEL": "yourchannel"
      }
    }
  }
}

To test from command line:

cd /path/to/ntfy-mcp
uvx --from . ntfy-mcp --channel yourchannel

Multiple MCP Servers

If you already have other MCP servers configured, just add ntfy to your existing configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token-here"
      }
    },
    "ntfy": {
      "command": "uvx",
      "args": ["--from", "/path/to/ntfy-mcp", "ntfy-mcp", "--channel", "yourchannel"]
    }
  }
}

Option 2: Run with Python directly

If you prefer to use Python directly:

{
  "mcpServers": {
    "ntfy": {
      "command": "python",
      "args": ["/path/to/ntfy_mcp.py", "--channel", "yourchannel"]
    }
  }
}

Note: You'll need to install dependencies first:

pip install mcp httpx pydantic

Configuration

Channel Configuration

The ntfy channel is now configured when starting the MCP server, not hardcoded in the script. You have two options:

Option 1: Command Line Argument (Recommended)

{
  "mcpServers": {
    "ntfy": {
      "command": "uvx",
      "args": ["--from", "/path/to/ntfy-mcp", "ntfy-mcp", "--channel", "mychannel"]
    }
  }
}

Option 2: Environment Variable

{
  "mcpServers": {
    "ntfy": {
      "command": "uvx",
      "args": ["--from", "/path/to/ntfy-mcp", "ntfy-mcp"],
      "env": {
        "NTFY_CHANNEL": "mychannel"
      }
    }
  }
}

Important: If no channel is configured, the MCP server will return a helpful error message explaining how to set it up.

Private Channels

For private ntfy.sh channels (requires ntfy.sh Pro), you'll need to add authentication headers. See ntfy.sh documentation for details.

Usage in Claude Desktop

After configuration, just ask Claude naturally:

Basic Examples (uses your configured default channel):

• "Notify me when you're done"
• "Send a notification to my phone saying 'Meeting in 10 minutes'"
• "Alert me when this analysis completes"
• "Send me a notification with high priority that deployment succeeded"

With emoji tags:

• "Send a notification with rocket emoji that the build is complete"
• "Notify me with a checkmark that all tests passed"

Channel Override Examples (when you have multiple channels):

• "Send a notification to the urgent-alerts channel that deployment failed"
• "Notify me on the family channel that dinner is ready"
• "Alert the dev-team channel that the build is complete"

Important: Claude will only use a different channel when you explicitly mention a specific channel name. The exact channel name you specify will be used, even if it appears to contain typos.

Available Emoji Tags

Common tags you can use:

• tada 🎉 - Celebration
• rocket 🚀 - Launch/deployment
• white_check_mark ✅ - Success
• warning ⚠️ - Warning
• x ❌ - Error/failure
• bell 🔔 - Reminder
• hourglass ⏳ - In progress
• fire 🔥 - Urgent/hot

Priority Levels

• min - Minimal priority
• low - Low priority
• default - Normal priority (default)
• high - High priority
• urgent - Urgent (triggers special notification behavior)

Troubleshooting

MCP Server won't start?

If the server fails to start, check the Claude Desktop logs for startup errors:

• macOS: tail -f ~/Library/Logs/Claude/mcp*.log
• Windows: type %APPDATA%\Claude\logs\mcp-server-ntfy.log

Common startup errors:

• "No default ntfy channel configured" - You need to add --channel yourchannel or set NTFY_CHANNEL environment variable
• "Command not found" - Wrong path to ntfy-mcp or missing uvx/python

Notifications not appearing?

1. Check subscription: Ensure you're subscribed to the correct channel in the ntfy app

2. Test manually: Run this in terminal:

   curl -d "Test message" ntfy.sh/yourchannel
   

   (Replace yourchannel with your configured channel) If you receive it, the issue is with the MCP server configuration.

3. Check Claude Desktop logs:

   • macOS: tail -f ~/Library/Logs/Claude/mcp*.log
   • Windows: type %APPDATA%\Claude\logs\mcp-server-ntfy.log

4. Verify config: Make sure the path in claude_desktop_config.json is correct

5. Restart Claude Desktop completely (quit, don't just close) after making configuration changes

Path Configuration Issues

Common path mistakes:

❌ Wrong: ~/Downloads/ntfy-mcp (don't use ~ in JSON) ✅ Correct: /Users/yourname/Downloads/ntfy-mcp

❌ Wrong: C:\Users\YourName\Downloads\ntfy-mcp (single backslash) ✅ Correct: C:\\Users\\YourName\\Downloads\\ntfy-mcp (double backslash in JSON)

❌ Wrong: Relative path like ./ntfy-mcp ✅ Correct: Absolute path /full/path/to/ntfy-mcp

To find the correct path:

# Navigate to the ntfy-mcp folder
cd /path/to/ntfy-mcp

# Get the full path
pwd
# Use this output in your config along with --channel yourchannel

How It Works

1. Claude Desktop starts the ntfy MCP server as a subprocess
2. The server runs on your local machine (not in Claude's sandbox)
3. When you ask Claude to send a notification, it calls the MCP server
4. The MCP server makes an HTTP POST to ntfy.sh
5. ntfy.sh delivers the notification to your phone

This architecture bypasses sandbox restrictions because the MCP server runs with your user's permissions.

Advanced Usage

Multiple Channels

You can send to different channels by explicitly mentioning them in your request:

• "Send a notification to the family channel saying dinner is ready"
• "Alert the urgent-alerts channel that the server is down"
• "Notify me on the work-updates channel about the meeting"

Important: Claude will only use a different channel when you explicitly mention it by name. It will not choose channels based on context or message content - only when you specifically request a different channel.

Custom Integration

The MCP server can be extended to support:

• Attachments (images, files)
• Actions (buttons in notifications)
• Scheduled notifications
• Message templates

See ntfy.sh documentation for available features: https://docs.ntfy.sh/

File Structure

ntfy-mcp/
├── ntfy_mcp.py        # Main MCP server implementation
├── pyproject.toml     # Python project configuration
├── LICENSE            # MIT License
├── .gitignore         # Git ignore rules for Python
└── README.md          # This file

License

MIT License

Copyright (c) 2024 ntfy-mcp contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Note: The ntfy.sh service is separate and has its own terms of service.

Support

• ntfy.sh documentation: https://docs.ntfy.sh/
• MCP documentation: https://modelcontextprotocol.io/
• Claude Desktop support: https://support.claude.com/

Credits

Built with:

• Model Context Protocol by Anthropic
• ntfy.sh by Philipp C. Heckel
• FastMCP Python SDK