-toast

This MCP server implements a Windows/macOS desktop notification service over the Model Context Protocol. It runs in Python 3.8+ and listens for MCP requests from clients such as VSCode Cline, then triggers desktop notifications on the host using win10toast on Windows and osascript on macOS. The server supports both synchronous and asynchronous MCP requests, multiple concurrent clients, and configurable notification parameters like title, message, display duration, icon (Windows only), subtitle and sound (macOS only), and a notification type (info, warning, error, success).

To use it, start the server with the provided invocation and then send MCP commands from a client. The server is designed to be compatible with VSCode Cline and follows the MCP protocol with appropriate error handling and logging so you can diagnose issues in real time.

Prerequisites:

• Python 3.8 or higher
• pip (comes with Python)

Install and run:

# 1) Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # on macOS/Linux
venv\Scripts\activate     # on Windows

# 2) Install dependencies (requirements.txt should list MCP-related libraries)
# If a requirements.txt is provided in the repo, install from it:
pip install -r requirements.txt

# 3) Run the MCP server (example)
python mcp_server.py --port 8000 --host 0.0.0.0

Optional runtime configuration can be provided via environment variables or additional CLI arguments as described in the README.

Tips and considerations:

• Ensure the host has the required notification tools installed: win10toast on Windows and macOS has built-in osascript support.
• The server binds to 0.0.0.0 by default to accept connections from any interface; use localhost (127.0.0.1) if you only need local access.
• Use a log level that suits your development or production needs (DEBUG during troubleshooting, INFO for normal operation).
• Validate MCP client requests to avoid malformed payloads; the server should return meaningful error messages for invalid commands.
• If you experience issues with notifications not appearing, check that the host OS allows desktop notifications from the Python process and that necessary permissions are granted.
• You can run multiple clients concurrently; ensure your networking configuration (firewall, ports) allows multiple connections to the chosen port.