mcp-notifications

MCP Notifications provides a real-time SSE-based notification service with a web dashboard and persistent storage via PocketBase. The server suite exposes two main tools for sending notifications: notify for simple messages and full_notify for feature-rich notices that can include links, images, priority, attachments, actions, and template data. You can connect to the SSE server from your MCP-enabled agents to receive instantaneous updates, and you can configure webhooks to deliver messages to platforms like Discord, Slack, Microsoft Teams, Feishu, Ntfy, or custom endpoints. The legacy MCP server component ensures backward compatibility with existing integrations while the newer Cloudflare Worker SSE server handles real-time streams and queue-based delivery.

To use the tools, run the legacy MCP server (or the desired server) and use the provided APIs or CLI wrappers to dispatch notifications. The REST API endpoint /api/notify accepts a JSON payload containing userId, message, and webhookConfig to route notifications to the configured providers. The two main tools (notify and full_notify) can be used by your automation scripts or agents to emit notifications with varying degrees of detail, including templates for common statuses like 'status', 'question', 'progress', and 'problem'.

Prerequisites:

• Git
• Node.js and npm (LTS version)
• Basic knowledge of running commands in a terminal

Steps:

1. Clone the repository:

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

2. Install dependencies for all workspaces:

npm install

3. Build all packages (monorepo):

npm run build

4. Install and build the legacy MCP server (for backward compatibility):

cd legacy
npm install
npm run build

5. Run the legacy MCP server locally (example):

node /path/to/legacy/build/index.js

6. Deploy or run the SSE server and web dashboard as needed (development flow):

• Deploy SSE Server (Cloudflare Worker):

cd apps/sse-server
npm run deploy

• Run Web Dashboard:

cd apps/web
npm run dev

Note: Update environment values (PocketBase URL, webhook endpoints) in the appropriate configuration files as described in the Configuration docs.

Tips and considerations:

• The current architecture is a monorepo with separate apps for the SSE server (Cloudflare Worker) and the Next.js web dashboard, plus a PocketBase-backed storage layer for webhooks and history.
• For production, configure PocketBase and the Cloudflare Worker with your actual URLs and credentials. The README references environment variables like POCKETBASE_URL and NEXT_PUBLIC_SSE_SERVER_URL; ensure these are set in your deployment environment.
• Webhook types supported include Discord, Slack, Microsoft Teams, Feishu, Ntfy, and a Generic JSON format. Use the Legacy Configuration example as a starting point for legacy integrations.
• If you’re using the legacy MCP server, you can pass environment variables to customize webhook behavior (e.g., WEBHOOK_URL, WEBHOOK_TYPE) when launching the server.
• The system includes rate limiting and a queue-based retry mechanism for webhook delivery; ensure your KV namespaces and queue bindings are correctly configured in your deployment (as described in the Configuration docs).
• For local development, you may build and run the legacy server, the SSE server, and the web dashboard in separate terminals to simulate end-to-end notification flows.