Ntfy MCP Server

🚀 Ntfy-MCP Server

The Ntfy-MCP Server is a Node.js-based tool designed to connect language models with the Ntfy.sh notification service through the Model Context Protocol (MCP). This project enables LLMs (Large Language Models) to send notifications directly to mobile phones or other devices.

🚀 Quick Start

The Ntfy-MCP Server provides a seamless way to integrate LLMs with the Ntfy notification service. Follow the steps below to get started.

Installation

npm install @model-context-protocol/core ntfy axios

Configuration

Edit the .env file in the project root directory:

NFTY_API_KEY=your_api_key_here # Required, your Ntfy API key
PORT=3001                    # Optional, default is 3001
DEBUG=true                   # Optional, enable debug mode

Starting the Server

# Start in development mode
npm run dev

# Build for production
npm run build

# Start the built application
npm start

✨ Features

Core Features

• Protocol Support: Implements the MCP protocol, allowing LLMs to send notifications by calling the API through the tool.
• Ntfy Integration: Supports all Ntfy features, including but not limited to:
  • Notification titles and content
  • Tags (#tag)
  • Priority settings
  • Delayed sending
  • Custom actions
• Multi-Topic Support: Enables different notification logics through different topics.

Tool Example

Sending Ntfy Notifications

{
  "tool_name": "send_ntfy",
  "args": {
    "topic": "string", // Required, Ntfy topic name
    "title?: string, // Optional, notification title
    "message?: string, // Optional, notification content
    "tags?: string[], // Optional, notification tags
    "priority?: number, // Optional, priority (1-5)
    "schedule?: string, // Optional, ISO 8601 formatted time string for delayed sending
    "actions?: {
      id: string,
      label: string,
      action: "view" | "http",
      url: string,
      method?: "GET" | "POST" | "PUT" | "DELETE",
      body?: string
    }[]
  }
}

📦 Installation

Install Dependencies

npm install @model-context-protocol/core ntfy axios

Configure Environment Variables

Edit the .env file in the project root directory:

NFTY_API_KEY=your_api_key_here # Required, your Ntfy API key
PORT=3001                    # Optional, default is 3001
DEBUG=true                   # Optional, enable debug mode

💻 Usage Examples

Basic Usage

In the MCP client:

<use_mcp_tool>
  <server_name>ntfy-mcp-server</server_name>
  <tool_name>send_ntfy</tool_name>
  <arguments>
    {
      "topic": "my-topic",
      "message": "This is a test notification."
    }
  </arguments>
</use_mcp_tool>

Advanced Usage

<use_mcp_tool>
  <server_name>ntfy-mcp-server</server_name>
  <tool_name>send_ntfy</tool_name>
  <arguments>
    {
      "topic": "my-topic",
      "title": "System Notification",
      "message": "Click the following link for more information.",
      "tags": ["system", "notification"],
      "actions": [
        {
          "id": "click_me",
          "label": "View Details",
          "action": "http",
          "url": "https://example.com/notification/123"
        }
      ]
    }
  </arguments>
</use_mcp_tool>

📚 Documentation

Directory Structure

src/
├── tools/                 # Tool module directory
│   └── send_ntfy.ts      # Implementation of the tool to send Ntfy notifications
├── services/             # Third-party service adapters
│   └── ntfy.ts          # Ntfy service adapter
└── main.ts               # Application entry file

Directory Structure Explanation

.
├── src/
│   ├── tools/
│   │   └── send_ntfy.ts       # Specific implementation of sending Ntfy notifications
│   ├── services/
│   │   └── ntfy.ts           # Adapter providing the Ntfy service interface
│   └── main.ts               # Application startup file
├── .env                       # Environment variable configuration file
└── package.json              # Project dependencies and script information

Project Characteristics

• Easy to Use: Quickly implement LLM-driven notification sending through the MCP protocol.
• Highly Customizable: Supports custom actions, priorities, and delay times to meet different scenario requirements.
• Stable and Reliable: Implemented based on Node.js and the official Ntfy SDK to ensure service stability.

Use Cases

Example 1: Mobile Phone Notifications

In the MCP client:

<use_mcp_tool>
  <server_name>ntfy-mcp-server</server_name>
  <tool_name>send_ntfy</tool_name>
  <arguments>
    {
      "topic": "my-phone",
      "message": "You have received a new email. Please check it."
    }
  </arguments>
</use_mcp_tool>

Example 2: Web Push

In the MCP client:

<use_mcp_tool>
  <server_name>ntfy-mcp-server</server_name>
  <tool_name>send_ntfy</tool_name>
  <arguments>
    {
      "topic": "web-notifications",
      "title": "System Message",
      "message": "There are new comments waiting to be processed.",
      "tags": ["system", "comment"]
    }
  </arguments>
</use_mcp_tool>

Available Scripts

# Start in development mode
npm run dev

# Build for production
npm run build

# Start the built application
npm start

Contribution Guidelines

1. Code Repository: GitHub Repository
2. Issue Reporting: Submit Issues or Pull Requests through GitHub.
3. Development Guidelines:
   • Follow the existing code style and structure of the project.
   • New features should be accompanied by unit tests.

Development Best Practices

• Logging: Enable debug mode in main.ts to facilitate problem troubleshooting.
• Dependency Management: Regularly check and update package dependencies to ensure compatibility.
• Module Division: Divide the code according to functional modules to keep the project structure clear.

📄 License

This project is open-source under the MIT License. For detailed license information, please refer to the LICENSE file.

For more details, please refer to the project's Wiki page or contact the maintainers.