{"id":37712789,"url":"https://github.com/zudsniper/mcp-notifications","last_synced_at":"2026-07-28T21:02:12.169Z","repository":{"id":286234039,"uuid":"960789806","full_name":"zudsniper/mcp-notifications","owner":"zudsniper","description":"Lightweight Node.js server sending webhook notifications. Ideal for devs using AI agents (e.g., Cursor) on multi-projects, alerting task completion for efficient switching. Features webhook alerts, multi-project dev, AI integration, easy setup for dev tools \u0026 automation.","archived":false,"fork":false,"pushed_at":"2025-09-03T18:57:58.000Z","size":942,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-02T01:28:17.023Z","etag":null,"topics":["mcp","mcp-server","modelcontextprotocol","notifications"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"tuberrabbit/mcp-server-notifier","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zudsniper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-05T04:26:18.000Z","updated_at":"2026-01-04T16:38:39.000Z","dependencies_parsed_at":"2025-08-27T17:34:05.591Z","dependency_job_id":"4899575b-ff12-435b-965f-5714e4ee2fcc","html_url":"https://github.com/zudsniper/mcp-notifications","commit_stats":null,"previous_names":["zudsniper/mcp-server-notifier"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/zudsniper/mcp-notifications","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zudsniper%2Fmcp-notifications","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zudsniper%2Fmcp-notifications/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zudsniper%2Fmcp-notifications/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zudsniper%2Fmcp-notifications/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zudsniper","download_url":"https://codeload.github.com/zudsniper/mcp-notifications/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zudsniper%2Fmcp-notifications/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36007830,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-28T02:00:06.341Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","modelcontextprotocol","notifications"],"created_at":"2026-01-16T13:21:20.959Z","updated_at":"2026-07-28T21:02:12.147Z","avatar_url":"https://github.com/zudsniper.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Notifications\n\n\u003e This project is a spiritual successor to the original `mcp-server-notifier` by [tuberrabbit@gmail.com](mailto:tuberrabbit@gmail.com), and has been significantly rewritten and is now maintained by [zudsniper](https://github.com/zudsniper).\n\nA modern, scalable notification service that integrates with MCP (Model Context Protocol) to send real-time notifications and webhooks when AI agents complete tasks. Now featuring a monorepo architecture with SSE (Server-Sent Events) support, Next.js web interface, and PocketBase integration.\n\n[简体中文文档](./docs/README_zh.md)\n\n![MCP Notifications](./docs/images/banner.png)\n\n## 🚀 What's New in v3.0\n\n- **Monorepo Architecture**: Organized as a workspace with separate apps and packages\n- **SSE Server**: Real-time notifications via Server-Sent Events (Cloudflare Worker with Durable Objects)\n- **Web Dashboard**: Next.js-based interface for monitoring and managing notifications\n- **PocketBase Integration**: Persistent storage for webhooks, connections, and notification history\n- **Enhanced Provider Support**: Improved webhook formatting for all major platforms\n- **Rate Limiting**: Built-in rate limiting with KV storage\n- **Connection Management**: Automatic cleanup and heartbeat for SSE connections\n- **TypeScript Throughout**: Full TypeScript support with shared types package\n\n## Features\n\n- **Real-time Notifications**: SSE-based push notifications for instant updates\n- **Webhook Notifications**: Receive alerts when your AI agents complete tasks\n- **Multiple Webhook Providers**: Support for Discord, Slack, Microsoft Teams, Feishu, Ntfy, and custom webhooks\n- **Image Support**: Include images in notifications via Imgur\n- **Multi-Project Support**: Efficiently manage notifications across different projects\n- **Easy Integration**: Simple setup with AI tools like Cursor\n- **Customizable Messages**: Send personalized notifications with title, body, and links\n- **Discord Embed Support**: Send rich, customizable Discord embed notifications\n- **NTFY Template Support**: Use pre-defined templates for status, questions, progress, and problems\n- **Notification History**: Track all notifications with PocketBase storage\n- **Fallback Support**: Configure backup webhooks for critical notifications\n- **Queue Processing**: Reliable webhook delivery with queue-based processing\n\n## Architecture\n\nThe v3.0 architecture consists of multiple components working together:\n\n1. **SSE Server (Cloudflare Worker)**: Manages real-time connections using Durable Objects\n2. **Web Dashboard (Next.js)**: User interface for monitoring and configuration\n3. **PocketBase**: Persistent storage for webhooks, templates, and history\n4. **Queue System**: Reliable webhook delivery with retry logic\n5. **Legacy MCP Server**: Backward compatibility for existing integrations\n\n### Data Flow\n\n```\nUser/AI Agent → SSE Server → Queue → Webhook Provider\n                    ↓           ↓\n              PocketBase   Rate Limiter\n                    ↓\n              Web Dashboard\n```\n\n## Project Structure\n\nThis is a monorepo organized with npm workspaces:\n\n```\nmcp-notifications/\n├── apps/\n│   ├── sse-server/      # Cloudflare Worker for SSE connections\n│   └── web/             # Next.js dashboard\n├── packages/\n│   └── shared/          # Shared types and utilities\n├── legacy/              # Legacy MCP server implementation\n└── pocketbase/          # PocketBase schema and migrations\n```\n\n## Installation\n\n### For Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/zudsniper/mcp-notifications.git\ncd mcp-notifications\n\n# Install dependencies for all workspaces\nnpm install\n\n# Build all packages\nnpm run build\n```\n\n### Deploy SSE Server (Cloudflare Worker)\n\n```bash\ncd apps/sse-server\nnpm run deploy\n```\n\n### Run Web Dashboard\n\n```bash\ncd apps/web\nnpm run dev\n```\n\n### Legacy MCP Server\n\nThe original MCP server is still available in the `legacy/` directory:\n\n```bash\ncd legacy\nnpm install\nnpm run build\n```\n\n## Integration\n\n### SSE Client Integration\n\nConnect to the SSE server from your application:\n\n```javascript\nimport { SSEClient } from '@mcp-notifications/shared';\n\nconst client = new SSEClient({\n  userId: 'user-123',\n  sseServerUrl: 'https://your-worker.workers.dev',\n  onNotification: (notification) =\u003e {\n    console.log('Received notification:', notification);\n  },\n  onConnectionStatus: (status) =\u003e {\n    console.log('Connection status:', status);\n  }\n});\n\nclient.connect();\n```\n\n### API Endpoints\n\nSend notifications via the REST API:\n\n```bash\ncurl -X POST https://your-worker.workers.dev/api/notify \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"userId\": \"user-123\",\n    \"message\": {\n      \"title\": \"Task Complete\",\n      \"body\": \"Your AI agent finished processing\"\n    },\n    \"webhookConfig\": {\n      \"type\": \"discord\",\n      \"url\": \"https://discord.com/api/webhooks/...\"\n    }\n  }'\n```\n\n### Legacy Cursor Integration\n\nFor the legacy MCP server:\n\n```json\n{\n   \"mcpServers\": {\n      \"notifier\": {\n         \"command\": \"node\",\n         \"args\": [\n            \"/path/to/legacy/build/index.js\"\n         ],\n         \"env\": {\n            \"WEBHOOK_URL\": \"https://ntfy.sh/webhook-url-example\",\n            \"WEBHOOK_TYPE\": \"ntfy\"\n         }\n      }\n   }\n}\n\n## Configuration\n\n### SSE Server Configuration (Cloudflare Worker)\n\nConfigure in `apps/sse-server/wrangler.toml`:\n\n```toml\nname = \"mcp-notifications-sse\"\nmain = \"src/index.ts\"\ncompatibility_date = \"2024-01-01\"\n\n[durable_objects]\nbindings = [{ name = \"SSE_CONNECTION_MANAGER\", class_name = \"SSEConnectionManager\" }]\n\n[[kv_namespaces]]\nbinding = \"RATE_LIMIT_KV\"\nid = \"your-kv-namespace-id\"\n\n[[queues.producers]]\nbinding = \"WEBHOOK_QUEUE\"\nqueue = \"webhook-notifications\"\n\n[vars]\nPOCKETBASE_URL = \"https://your-pocketbase-instance.com\"\n```\n\n### Web Dashboard Configuration\n\nConfigure in `apps/web/.env.local`:\n\n```bash\nNEXT_PUBLIC_SSE_SERVER_URL=https://your-worker.workers.dev\nNEXT_PUBLIC_POCKETBASE_URL=https://your-pocketbase-instance.com\n```\n\n### PocketBase Setup\n\n1. Deploy PocketBase instance\n2. Import schema: `pocketbase/pb_schema.json`\n3. Run migrations for initial templates\n\n### Supported Webhook Types\n\n- **Discord**: Rich embeds with colors and fields\n- **Slack**: Blocks and attachments  \n- **Microsoft Teams**: Adaptive cards\n- **Feishu**: Interactive cards\n- **Ntfy**: Priority levels and actions\n- **Generic JSON**: Custom webhook format\n\n### Legacy Configuration\n\nFor the legacy MCP server, create `legacy/webhook-config.json`:\n\n```json\n{\n  \"webhook\": {\n    \"type\": \"discord\",\n    \"url\": \"https://discord.com/api/webhooks/your-webhook-url\",\n    \"name\": \"My Notifier\"\n  },\n  \"imgur\": {\n    \"clientId\": \"your-imgur-client-id\"\n  }\n}\n```\n\nSee the [Configuration Guide](./docs/CONFIGURATION.md) for full details and examples.\n\n## Usage\n\nFor detailed usage instructions, see the [Usage Guide](./docs/USAGE.md).\n\n### Available Tools\n\nThis package provides two tools for sending notifications:\n\n1. `notify` - for simple notifications.\n2. `full_notify` - for more advanced notifications with all features.\n\n#### `notify`\nSend a simple notification with body, optional title, and optional template.\n\n**Input**:\n- `body`: The main content of the notification message.\n- `title` (optional): The title for the notification.\n- `template` (optional): A predefined template to use (e.g., 'status', 'question', 'progress', 'problem').\n\n**Example**:\n```javascript\n// AI agent call\nawait run(\"notify\", {\n  title: \"Task Completed\",\n  body: \"I have finished the task.\"\n});\n```\n\n#### `full_notify`\nSend a detailed notification with advanced options like a link, image, priority, attachments, actions, and template data.\n\n**Input**:\n- `body`: The main content of the notification message.\n- `title` (optional): The title for the notification.\n- `link` (optional): A URL to include in the notification.\n- `imageUrl` (optional): The URL of an image to include.\n- `image` (optional): The local file path for an image to upload to Imgur.\n- `priority` (optional, ntfy only): Notification priority level from 1-5 (5 is the highest).\n- `attachments` (optional, ntfy only): A list of URLs to attach to the notification.\n- `template` (optional): A predefined template to use.\n- `templateData` (optional): Data to be used with the selected template.\n- `actions` (optional, ntfy only): Interactive action buttons for the notification.\n\n**Example**:\n```javascript\n// AI agent call\nawait run(\"full_notify\", {\n  title: \"Server Alert\",\n  body: \"Disk usage is high!\",\n  priority: 5,\n  actions: [\n    {\n      action: \"view\",\n      label: \"Open Grafana\",\n      url: \"https://grafana.example.com/d/abcdefg\"\n    }\n  ]\n});\n```\n\n### NTFY Templates\n\nWhen using ntfy.sh as your webhook provider, you can use the following predefined templates with the `template` and `templateData` parameters:\n\n- `status`: For sending status updates.\n- `question`: For asking questions.\n- `progress`: For tracking the progress of long-running tasks.\n- `problem`: For reporting errors or issues.\n\nSee [docs/NOTIFICATIONS.md](./docs/NOTIFICATIONS.md) for more details on templates.\n\n## Development\n\n### Setting Up Development Environment\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/zudsniper/mcp-notifications.git\ncd mcp-notifications\n```\n\n2. Install dependencies for all workspaces:\n```bash\nnpm install\n```\n\n3. Build all packages:\n```bash\nnpm run build\n```\n\n### Development Commands\n\n```bash\n# Run SSE server locally\ncd apps/sse-server\nnpm run dev\n\n# Run web dashboard\ncd apps/web\nnpm run dev\n\n# Build shared package\ncd packages/shared\nnpm run build\n\n# Test legacy server\ncd legacy\nnpm run test\n```\n\n### Testing Webhooks\n\nTest scripts are available in `legacy/src/`:\n- `test-discord.js` - Test Discord webhooks\n- `test-ntfy.js` - Test ntfy notifications\n- `test-slack.js` - Test Slack webhooks\n\n### Deployment\n\n#### Deploy SSE Server to Cloudflare\n\n```bash\ncd apps/sse-server\nnpm run deploy\n```\n\n#### Deploy Web Dashboard to Vercel\n\n```bash\ncd apps/web\nvercel\n```\n\n## Migration Guide\n\n### Migrating from v2.x to v3.0\n\n1. **Legacy Support**: The original MCP server is still available in `legacy/` directory\n2. **New Features**: Consider adopting SSE for real-time notifications\n3. **Database**: Set up PocketBase for persistent storage\n4. **API Changes**: Update API calls to use new endpoints\n\nSee [MIGRATION.md](./docs/MIGRATION.md) for detailed migration instructions.\n\n## Performance\n\n- **SSE Connections**: Support for thousands of concurrent connections via Durable Objects\n- **Rate Limiting**: Built-in protection against abuse (10 requests/minute default)\n- **Queue Processing**: Reliable webhook delivery with automatic retries\n- **Edge Computing**: Global distribution via Cloudflare Workers\n\n## Security\n\n- **Authentication**: Token-based auth for ntfy webhooks\n- **Rate Limiting**: KV-based rate limiting per user\n- **CORS**: Configurable CORS headers for web clients\n- **Input Validation**: Zod schemas for all API inputs\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Acknowledgments\n\n- Original `mcp-server-notifier` by tuberrabbit@gmail.com\n- Maintained and enhanced by [zudsniper](https://github.com/zudsniper)\n- Built with Cloudflare Workers, Next.js, and PocketBase\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzudsniper%2Fmcp-notifications","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzudsniper%2Fmcp-notifications","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzudsniper%2Fmcp-notifications/lists"}