mcp_server_notify

This MCP server implements a notification provider that uses Apprise to deliver desktop notifications with a sound cue when an agent task completes. It is built as a Python package named mcp-server-notify and can be run via the uv service manager or directly with Python. You configure it to listen to MCP events and trigger a local desktop notification on task completion, with optional sound files included in the package. To run it through uv, point uv at the local project directory and use the run command for mcp-server-notify. You can also run the module directly with Python for testing or development.

Typical usage involves adding the server to your MCP workflow so that when an agent finishes a task, the MCP server sends a notification to your desktop. This is useful for staying informed without switching apps, especially when running long tasks or remote sessions. The server relies on Apprise to handle the notification delivery across different desktop environments, and it supports Windows, macOS, and Linux.

Prerequisites:

• Python 3.8+ installed on your system
• pip and venv support
• Access to the internet to install dependencies

Install steps:

1. Clone or download the repository:

git clone https://github.com/Cactusinhand/mcp_server_notify.git
cd mcp_server_notify

2. Create a virtual environment and activate it:

python -m venv .venv
# Windows
 .venv\Scripts\activate
# macOS/Linux
 source .venv/bin/activate

3. Install the package (from PyPI) or from source:

# Install from PyPI (preferred)
pip install mcp-server-notify

# Or install from source in editable mode
pip install -e .

4. Test the installation by running the module directly:

python -m mcp_server_notify

5. If you plan to run via uv configuration, ensure uv is installed:

pip install uv

6. Configure your MCP client to use the notifier, for example with uv as shown in the usage example below.

Notes and tips:

• This server uses Apprise for desktop notifications. Some platforms require additional system dependencies:
  • Windows: install pywin32 if using Windows notifications
  • macOS: ensure terminal-notifier is installed (brew install terminal-notifier)
• Docker support is not provided due to host OS notification access limitations.
• If running via Python directly, you can pass --debug or --log-file options to assist troubleshooting.
• The configuration example uses uv for orchestration; you can alternatively run the module with python -m mcp_server_notify and supply appropriate arguments.
• If you customize notification contents or assets, ensure paths to any included sound files are correct and accessible by the running process.