Home / MCP / Toast MCP Server

Toast MCP Server

Provides a Python MCP server that shows desktop notifications on Windows 10 and macOS in response to MCP client commands.

python

3stars

View on GitHub

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
    "mcpServers": {
        "toast_mcp": {
            "command": "python",
            "args": [
                "mcp_server.py",
                "--port",
                "8000",
                "--host",
                "0.0.0.0"
            ]
        }
    }
}

You can run a small MCP server that listens for client requests and displays desktop notifications on Windows 10 or macOS. This server uses Python 3.8+ and supports both local (stdio) execution and a configurable HTTP interface to trigger notifications from MCP clients like VSCode Cline. It binds to 0.0.0.0 by default to accept remote connections, and it exposes a simple, practical API to trigger visible alerts on your desktop.

How to use

Install and run the server locally, then connect your MCP client to trigger desktop notifications. Start the server so it listens on all interfaces and a chosen port, then send MCP commands from your client to display notices on your screen.

How to install

Prerequisites you need to meet before proceeding:

Python 3.8 or newer installed on your system
Access to a terminal or command prompt

Step by step commands to get started:

pip install -r requirements.txt
```

If you clone or download a project folder that contains a Python script named `mcp_server.py`, you can run the server directly with Python.

python mcp_server.py --port 8000 --host 0.0.0.0

Configuration and usage notes

The server binds to all network interfaces by default (0.0.0.0) and listens on a configurable port (default 8000). You can customize the host and port using command line arguments. The server supports multiple concurrent MCP client connections and includes basic error handling and logging to help you diagnose issues.

Security, logging, and reliability

- Validate inputs from MCP clients to prevent malformed commands from triggering notifications. - Maintain comprehensive logs for connections, commands, and errors to aid debugging. - Implement a clean shutdown path to ensure notifications stop gracefully when stopping the server.

Examples of how to trigger notifications (usage patterns)

From an MCP client, send a notification command to the running server. The server translates that command into a system notification on Windows 10 via win10toast or on macOS via osascript, with options for title, message, duration, icon (Windows only), subtitle (macOS only), and notification type (information, warning, error, success). Use simple, client-friendly API calls to create alerts for you and teammates.

Troubleshooting

- If the server fails to start, check that Python 3.8+ is installed and that port 8000 is not in use by another process. - If notifications do not appear, verify the host binding (0.0.0.0) and ensure the MCP client is targeting the correct host/port. - Review logs for any command validation errors and adjust the client request formatting accordingly.

Notes

This server is designed to be lightweight and focused on desktop notifications. It emphasizes practical, direct usage with MCP clients and clear runtime behavior. You can extend or adapt the command handling to suit additional notification parameters as needed.

Usage example run command

python mcp_server.py --port 8000 --host 0.0.0.0