https://github.com/cactusinhand/mcp_server_notify
Send system notification when Agent task is done.
https://github.com/cactusinhand/mcp_server_notify
mcp mcp-server notification
Last synced: 3 months ago
JSON representation
Send system notification when Agent task is done.
- Host: GitHub
- URL: https://github.com/cactusinhand/mcp_server_notify
- Owner: Cactusinhand
- License: mit
- Created: 2025-03-16T04:16:19.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-05-10T10:50:42.000Z (5 months ago)
- Last Synced: 2025-06-17T13:08:56.193Z (4 months ago)
- Topics: mcp, mcp-server, notification
- Language: Python
- Homepage:
- Size: 60.5 KB
- Stars: 18
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://mseep.ai/app/cactusinhand-mcp-server-notify) [](https://badge.fury.io/py/mcp-server-notify)
# 📢 MCP Notify Server
[English](README.md) | [中文](README.zh.md)
A MCP server that send desktop notifications with sound effect when agent tasks are completed.
## 🥩 Features
- Send system desktop notifications after agent tasks completion
- Play alert sounds to grab user attention, with sound file inside.
- Cross-platform support (Windows, macOS, Linux)
- Based on standard MCP protocol, integrates with various LLM clients
## ⏬ Installation
### Install using [uv](https://docs.astral.sh/uv/) package manager
```bash
git clone https://github.com/Cactusinhand/mcp_server_notify.git
cd mcp_server_notify
uv venv
source .venv/Scripts/activate
uv pip install mcp-server-notify
# or
pip install mcp-server-notify
```
After installation, call the module directly to check if installation was successful:
```bash
python -m mcp_server_notify
```
This module accepts ` --debug ` or `--file ` option, we can use it like:
```shell
python -m mcp_server_notify --debug
python -m mcp_server_notify --debug --log-file=path/to/logfile.log
```
## ⚠️❕ Special requirements
** We use [Apprise](https://github.com/caronc/apprise) API for our Desktop notification deliver，so we need to install some special requirements in our Desktop **
**Windows**
```shell
# windows:// minimum requirements
pip install pywin32
```
**macOS**
```shell
# Make sure terminal-notifier is installed into your system
brew install terminal-notifier
```
## 📚 Usage
### Using with Claude Desktop:
Find the configuration file `claude_desktop_config.json`
```json
{
"mcpServers": {
"NotificationServer": {
"command": "uv",
"args": [
"--directory",
"path/to/your/mcp_server_notify project",
"run",
"mcp-server-notify",
]
}
}
}
```
If installed globally, you can also use the python command:
```json
{
"mcpServers": {
"NotificationServer": {
"command": "python",
"args": [
"-m",
"mcp_server_notify",
]
}
}
}
```
### ⚡️ Using with Cursor:
Find the configuration file `~/.cursor/mcp.json` or `your_project/.cursor/mcp.json`
```json
{
"mcpServers": {
"NotificationServer": {
"command": "uv",
"args": [
"--directory",
"path/to/your/mcp_server_notify project",
"run",
"mcp-server-notify",
]
}
}
}
```
After configuration, simply add a prompt like `finally, send me a notification when task finished.` at the end of your task input to the AI to trigger notifications.
In Cursor, you can add this prompt as a rule in `Cursor Settings` -> `Rules` so you don't have to type it manually each time.
### ⚡️ Using with VSCode + Copilot:
1. Install the service manager [uv/uvx](https://docs.astral.sh/uv/):
`pip install uv`
2. Add the service to VSCode settings:
Windows `%APPDATA%\Code\User\settings.json`
macOS `$HOME/Library/Application\ Support/Code/User/settings.json`
Linux `$HOME/.config/Code/User/settings.json`
```json
"mcp": {
"servers": {
"notifier": {
"command": "uvx",
"args": [
"mcp-server-notify"
],
"env": {}
}
}
}
```
3. Make sure you are using the latest VSCode version — it automatically runs MCP services
4. Open VSCode → enable Copilot → switch to agent mode.
5. Type # → you will see the #send_notification option.
6. Ask the agent: run #send_notification (it will handle the notification automatically).
7. Now the Copilot in agent mode can send desktop notifications.
### 🐳 Running with Docker
Currently not available due to environment compatibility issues.
If Docker containers need to trigger host notifications regardless of whether the host OS is Windows, macOS, or Linux, the solution becomes much more complex, and direct use of native notifications is usually not feasible.
Main issues:
1. OS-specific notification systems
Each operating system (Windows, macOS, Linux) has its unique notification mechanism.
2. Docker isolation
The isolation of Docker containers limits their ability to access host operating system resources directly.
3. Dependency management
Need to handle different notification libraries and dependencies for each operating system.
## 🧾 License
MIT
## 💻 Contributions
Issues and pull requests are welcome!