Content
# agent-notifier-mcp
Local MCP server for AI agent audio, TTS, and popup notifications.
`agent-notifier-mcp` lets AI agents report their task state through local desktop notifications:
- short sounds for start/progress/error/question events;
- optional looped audio until `reset_notifications`;
- optional offline TTS;
- optional topmost popup windows with a close button;
- reset/stop tools for looped sounds and popups.
## Use case
When an AI coding agent starts a long task, gets blocked, asks a question, fails, or finishes, it can call an MCP tool and notify you even if you moved away from the PC.
## Available tools
- `project_started`
- `project_progress`
- `project_done`
- `agent_error`
- `agent_question`
- `notify_custom`
- `stop_audio`
- `reset_notifications`
## Install
```bash
git clone https://github.com/NewYaroslav/agent-notifier-mcp.git
cd agent-notifier-mcp
uv sync
```
Or with plain Python:
```bash
python -m venv .venv
.venv\Scripts\activate
pip install -e .
```
## MCP config example
```json
{
"mcpServers": {
"agent-notifier": {
"command": "uv",
"args": ["run", "agent-notifier-mcp"],
"cwd": "E:/_repoz/agent-notifier-mcp"
}
}
}
```
## Audio files
Put your custom sounds into `assets/sounds/` and reference them by file name:
```text
assets/sounds/started.wav
assets/sounds/progress.wav
assets/sounds/done.mp3
assets/sounds/error.wav
assets/sounds/question.wav
```
If a sound file is missing, the server falls back to a short system beep where possible.
## Configuration
Optional config file: `config/agent_notifier.json`.
You can override its path with:
```bash
set AGENT_NOTIFIER_CONFIG=E:\path\to\agent_notifier.json
```
Example:
```json
{
"default_tts": true,
"default_popup": false,
"events": {
"project_started": {
"sound": "started.wav",
"tts": true,
"popup": false,
"loop_sound": false
},
"project_done": {
"sound": "done.mp3",
"tts": true,
"popup": true,
"loop_sound": false
}
}
}
```
## Typical agent instruction
```text
When starting a non-trivial task, call project_started.
During long work, call project_progress occasionally.
When finished, call project_done with a short result summary.
If blocked by an error, call agent_error.
If user input is required, call agent_question.
Use reset_notifications to stop looped audio and close popups.
```
## License
MIT
