# Windows System Sounds MCP Server

An MCP server for Windows that plays built-in Windows system sounds or existing WAV files.

It can be used with LM Studio or any other MCP-compatible client to notify the user when a local model finishes a stage, needs attention, requests permission, or completes the whole task.

The server uses the standard Windows `winsound` module and does not require downloading additional audio files.

---

## Features

- One MCP tool: `play_sound`.
- Two built-in presets:
  - `attention` — stage finished, user attention needed, or permission requested.
  - `done` — whole job finished.
- Plays WAV files from the Windows Media folder:
  - `%SystemRoot%\Media`
- Plays WAV files by full path:
  - `C:/my-sounds/my_sound.wav`
- Repeats a sound multiple times.
- Pause between repeats: 3 seconds.
- - Minimal diagnostic `stderr` output by default.
- Optional debug logging via `SOUND_MCP_DEBUG`.

---

## Requirements

- Windows
- Python 3.10 or newer
- LM Studio or another MCP client
- `mcp` Python package

---

## Installation

Install the MCP SDK:

```bash
python -m pip install --upgrade pip
python -m pip install "mcp[cli]"
```

Save `sound_mcp_server.py` to a folder, for example:

```text
C:\mcp\sound_mcp_server.py
```

---

## LM Studio configuration

Example MCP server configuration:

```json
{
  "mcpServers": {
    "windows-system-sounds": {
      "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": [
        "C:\\mcp\\sound_mcp_server.py"
      ]
    }
  }
}
```

Replace the Python path and script path with your actual paths.

To find your Python executable path, run:

```bash
python -c "import sys; print(sys.executable)"
```

Restart LM Studio after adding the server.

---

## Tool: `play_sound`

The server exposes one tool:

```text
play_sound
```

### Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---:|---:|---|
| `sound_type` | `"attention"` \| `"done"` | No | `null` | Built-in preset. Not required if `system_file` or `full_path` is provided. |
| `system_file` | `string` | No | `null` | WAV file name from `%SystemRoot%\Media`. |
| `full_path` | `string` | No | `null` | Full path to a WAV file. |
| `repeat` | `integer` | No | `1` | Number of playback repeats. Pause between repeats is 3 seconds. |

At least one sound source must be specified:

- `sound_type`
- or `system_file`
- or `full_path`

If both `system_file` and `full_path` are provided, the server returns an error.

---

## Examples

### Attention preset

```json
{
  "name": "play_sound",
  "arguments": {
    "sound_type": "attention"
  }
}
```

### Done preset

```json
{
  "name": "play_sound",
  "arguments": {
    "sound_type": "done"
  }
}
```

### Play a file from the Windows Media folder

```json
{
  "name": "play_sound",
  "arguments": {
    "system_file": "Windows Notify Calendar.wav"
  }
}
```

### Play a file by full path

```json
{
  "name": "play_sound",
  "arguments": {
    "full_path": "C:/my-sounds/my_sound.wav"
  }
}
```

### Repeat a sound three times

```json
{
  "name": "play_sound",
  "arguments": {
    "system_file": "Windows Notify Calendar.wav",
    "repeat": 3
  }
}
```

Playback order:

```text
play
pause 3 seconds
play
pause 3 seconds
play
```

No extra pause is added after the last repeat.

---

## Logging

The server produces minimal diagnostic `stderr` output by default.

Debug logging can be enabled with the environment variable:

```text
SOUND_MCP_DEBUG=1
```

Example LM Studio configuration with debug logging:

```json
{
  "mcpServers": {
    "windows-system-sounds": {
      "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": [
        "C:\\mcp\\sound_mcp_server.py"
      ],
      "env": {
        "SOUND_MCP_DEBUG": "1"
      }
    }
  }
}
```

Some MCP clients, including LM Studio, may display MCP server `stderr` output as `[ERROR]` even when the message is only diagnostic.

---

## Security notes

The `full_path` parameter can play arbitrary WAV files on the local machine.

For local personal use this is usually fine.

If the server is exposed to untrusted clients, consider:

- removing `full_path` support;
- or allowing only specific directories;
- or using only `system_file`.

---

## Limitations

- Windows only.
- Only `.wav` files are supported.
- `system_file` accepts only a file name, not a folder path.
- `full_path` must be an absolute path to an existing file.

---

## Recommended System Prompt

To make the local model use the tool automatically, add the following instructions to your LM Studio system prompt:

```text
When an important stage is finished or user permission is required, call:
play_sound(sound_type="attention")

When the whole job is fully finished, call:
play_sound(sound_type="done")
```
(You can also find this prompt in the [examples/prompts.md](examples/prompts.md)).

---

## License

MIT. See [LICENSE](LICENSE).