https://github.com/tomekkorbak/voice-status-report-mcp-server
A Model Context Protocol (MCP) server that provides voice status updates using OpenAI's text-to-speech API.
https://github.com/tomekkorbak/voice-status-report-mcp-server
claude-code cursor mcp mcp-server tts
Last synced: 5 months ago
JSON representation
A Model Context Protocol (MCP) server that provides voice status updates using OpenAI's text-to-speech API.
- Host: GitHub
- URL: https://github.com/tomekkorbak/voice-status-report-mcp-server
- Owner: tomekkorbak
- License: mit
- Created: 2025-04-05T13:38:47.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-06-05T15:39:58.000Z (6 months ago)
- Last Synced: 2025-06-05T16:39:47.371Z (6 months ago)
- Topics: claude-code, cursor, mcp, mcp-server, tts
- Language: Python
- Homepage:
- Size: 375 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - **Voice Status Report** - An MCP server that provides voice status updates using OpenAI's text-to-speech API, to be used with Cursor or Claude Code. `api` `http` `ai` `openai` `git` (📦 Other)
README
# Voice Status Report MCP Server
 [](https://badge.fury.io/py/voice-status-report-mcp-server) [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/release/python-3120/) [](https://cursor.com/install-mcp?name=voice-status-report&config=eyJjb21tYW5kIjoidXZ4IHZvaWNlLXN0YXR1cy1yZXBvcnQtbWNwLXNlcnZlciIsImVudiI6eyJPUEVOQUlfQVBJX0tFWSI6IllPVVJfT1BFTkFJX0FQSV9LRVkifX0%3D)
A [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server that provides voice status updates using [OpenAI's text-to-speech API](https://platform.openai.com/docs/guides/text-to-speech). This allows language models to communicate with users through short voice messages: reporting on the progress of a task, or confirming that a command has been executed. It's espesially useful when working with Cursor or Claude code: you can give the agent a task, go on to do something else but keep receiving status reports on agent's progess and when it's done with its task and needs your attention.
This MCP server is meant to be batteries included: the description of the `summarize` tool (prepended to system message by most MCP clients) asks the model to use this tool to report on the progress of a task.
## Available Tools
The server exposes the following tool:
- `summarize(text: str)`: Converts the provided text into speech using OpenAI's TTS API and plays it to the user. This is useful for providing status updates or confirmations after code changes or commands.
## Usage
You'll need an OpenAI API key to use this server.
### Claude for Desktop
Update your `claude_desktop_config.json` (located in `~/Library/Application\ Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%/Claude/claude_desktop_config.json` on Windows) to include the following:
```json
{
"mcpServers": {
"voice-status-report": {
"command": "uvx",
"args": [
"voice-status-report-mcp-server"
],
"env": {
"OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
}
}
}
}
```
## Command Line Options
The server accepts the following command line options:
- `--ding`: Enable the ding sound that plays before each voice message. By default, the ding sound is disabled.
- `--voice [VOICE]`: Choose the voice for speech generation. Available options: `alloy`, `ash`, `coral` (default), `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer`.
- `--speed SPEED`: Set the speech speed (0.5-4.0, where higher is faster). Default is 4.0.
- `--instructions TEXT`: Provide custom voice instructions for the TTS model. By default, the server uses a preset instruction for a calm, friendly voice.
### Examples
```bash
# Run with ding sound enabled and a different voice
voice-status-report-mcp-server --ding --voice nova
# Run with a slower speech speed
voice-status-report-mcp-server --speed 2.0
# Run with custom voice instructions
voice-status-report-mcp-server --instructions "Voice should be confident and authoritative"
```
### Claude for Desktop Configuration Examples
```json
{
"mcpServers": {
"voice-status-calm": {
"command": "uvx",
"args": [
"voice-status-report-mcp-server",
],
"env": {
"OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
}
},
}
}
```
When using non-default arguments, you can use the following configuration:
```json
{
"mcpServers": {
"voice-status-report-mcp-server": {
"command": "uvx",
"args": [
"voice-status-report-mcp-server",
"--ding",
"--voice", "nova",
"--speed", "3.0",
"--instructions", "Voice should be confident and authoritative"
],
"env": {
"OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
}
}
}
}
```
## Example Usage
Once connected, Claude can use the tool to provide audio feedback like:
- "Added a new function to handle user authentication"
- "Fixed the bug in the login form"
- "Created a new file for the API client"
- "Added OpenAI TTS documentation link"
## License
This project is licensed under the MIT License - see the LICENSE file for details.