MCP Server Notifier

A lightweight notification service that integrates with MCP (Model Context Protocol) to send webhooks when AI agents complete tasks.

简体中文文档

Authors

Originally created by tuberrabbit@gmail.com.
Currently maintained by zudsniper.

Features

• Webhook Notifications: Receive alerts when your AI agents complete tasks
• Multiple Webhook Providers: Support for Discord, Slack, Microsoft Teams, Feishu, Ntfy, and custom webhooks
• Image Support: Include images in notifications via Imgur
• Multi-Project Support: Efficiently manage notifications across different projects
• Easy Integration: Simple setup with AI tools like Cursor
• Customizable Messages: Send personalized notifications with title, body, and links

Installation

Option 1: Using npm

npm install -g mcp-server-notifier

Option 2: Using Docker

docker pull zudsniper/mcp-server-notifier:latest

# Run with environment variables
docker run -e WEBHOOK_URL=https://your-webhook-url -e WEBHOOK_TYPE=discord zudsniper/mcp-server-notifier

Option 3: From Source

git clone https://github.com/zudsniper/mcp-server-notifier.git
cd mcp-server-notifier
npm install
npm run build

Integration

Cursor Integration

1. Go to your 'Cursor Settings'
2. Click MCP in the sidebar, then click + Add new global MCP server
3. Add mcp-server-notifier.

{
   "mcpServers": {
      "notifier": {
         "command": "npx",
         "args": [
            "-y",
            "mcp-server-notifier"
         ],
         "env": {
            "WEBHOOK_URL": "https://ntfy.sh/webhook-url-example",
            "WEBHOOK_TYPE": "ntfy"
         }
      }
   }
}

Configuration

By default, the notifier supports several webhook types:

• Discord
• Slack
• Microsoft Teams
• Feishu
• Ntfy
• Generic JSON

You can specify the webhook type and URL through environment variables:

env WEBHOOK_URL="https://your-webhook-url" WEBHOOK_TYPE="discord" npx -y mcp-server-notifier

Authentication Tokens

WEBHOOK_TOKEN is an optional environment variable. When set, it will be included as a Bearer token in the Authorization header only for ntfy webhook requests. If WEBHOOK_TOKEN is not set, no Authorization header is sent.

• Basic Authentication is not supported.
• This token is ignored by all other webhook providers (Discord, Slack, Teams, Feishu, Generic JSON).

Example:

env WEBHOOK_URL="https://ntfy.sh/your-topic" WEBHOOK_TYPE="ntfy" WEBHOOK_TOKEN="your-secret-token" npx -y mcp-server-notifier

Configuration File

For more advanced configuration, you can create a webhook-config.json file:

{
  "webhook": {
    "type": "discord",
    "url": "https://discord.com/api/webhooks/your-webhook-url",
    "name": "My Notifier"
  },
  "imgur": {
    "clientId": "your-imgur-client-id"
  }
}

See the Configuration Guide for full details and examples.

Usage

• Ask your AI agent to notify you with a custom message when a task is complete
• Configure it as a persistent rule in Cursor settings to avoid repeating the setup

For detailed usage instructions, see the Usage Guide.

Available Tools

1. notify
   • Purpose: Send rich notifications to any configured webhook
   • Input:
     • message - Text content of the notification
     • title (optional) - Title for the notification
     • link (optional) - URL to include in the notification (used as click action for ntfy)
     • imageUrl (optional) - URL of an image to include (legacy, use image or attachments)
     • image (optional) - Local file path of an image to upload to Imgur
     • priority (optional, ntfy only) - Notification priority (1-5)
     • attachments (optional, ntfy only) - Array of URLs to attach
     • template (optional, ntfy only) - Predefined template to use: status, question, progress, problem
     • templateData (optional, ntfy only) - Data to populate the chosen template
     • actions (optional, ntfy only) - Array of action button definitions (view or http)
   • Best for: General notification needs

Note: Template functionality is currently under development and has limited support. Templates work best with ntfy.sh but may not be fully implemented for all webhook providers. See the ROADMAP.md file for future implementation plans.

NTFY Templates

When using ntfy.sh as your webhook provider, you can use the following predefined templates:

1. Status Template (status)

   • Purpose: Send status updates about systems, processes, or tasks
   • Data Fields:
     • status - Current status (e.g., "online", "completed", "pending")
     • details (optional) - Additional information about the status
     • timestamp (optional) - When this status was recorded
     • component (optional) - The system component this status applies to

2. Question Template (question)

   • Purpose: Ask questions that require a response
   • Data Fields:
     • question - The main question being asked
     • context (optional) - Background information for the question
     • options (optional) - Possible answer options
     • deadline (optional) - When a response is needed by

3. Progress Template (progress)

   • Purpose: Track progress of long-running tasks
   • Data Fields:
     • title - Name of the task or process
     • current - Current progress value
     • total - Total value to reach completion
     • percentage (optional) - Explicit percentage value (calculated if not provided)
     • eta (optional) - Estimated time to completion
     • details (optional) - Additional information about the progress

4. Problem Template (problem)

   • Purpose: Report errors or issues
   • Data Fields:
     • title - Short description of the problem
     • description (optional) - Detailed information about the problem
     • severity (optional) - How severe the problem is (e.g., "critical", "warning")
     • source (optional) - Where the problem originated
     • timestamp (optional) - When the problem occurred
     • solution (optional) - Suggested ways to fix the problem

Example Using Template:

// Send a progress notification
{
  "template": "progress",
  "templateData": {
    "title": "Database Backup",
    "current": 75,
    "total": 100,
    "eta": "2 minutes remaining",
    "details": "Compressing backup files"
  },
  "priority": 3
}

Docker Support

The MCP Server Notifier is available as a Docker image:

docker pull zudsniper/mcp-server-notifier:latest

Run with environment variables:

docker run -e WEBHOOK_URL=https://your-webhook-url -e WEBHOOK_TYPE=discord zudsniper/mcp-server-notifier

Example Configurations

Example webhook configurations are available in the examples directory.

Development

Setting Up Development Environment

1. Clone the repository:

git clone https://github.com/zudsniper/mcp-server-notifier.git
cd mcp-server-notifier

2. Install dependencies:

npm install

3. Build the project:

npm run build

Testing Your Changes

1. Run the MCP server in development mode:

# Install the MCP Inspector if you haven't already
npm install -g @modelcontextprotocol/inspector

# Start the server with the Inspector
npx @modelcontextprotocol/inspector node build/index.js

2. The Inspector provides a web interface where you can:
   • Send requests to your tools
   • View request/response logs
   • Debug issues with your implementation

Releasing New Versions

To release a new version:

1. Update version in package.json
2. Push changes to the release branch
3. GitHub Actions will automatically:
   • Run tests
   • Build and push Docker images
   • Publish to npm
   • Create a GitHub Release

Required repository secrets for CI/CD:

• DOCKERHUB_USERNAME - Docker Hub username
• DOCKERHUB_TOKEN - Docker Hub access token
• NPM_TOKEN - npm access token

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.