Voice Status Report MCP Server

🚀 Voice Status Report MCP Server

A Model Context Protocol (MCP) server that provides voice status updates using OpenAI's text-to-speech API. This enables language models to communicate with users via short voice messages, such as reporting task progress or confirming command execution. It's particularly useful when used with Cursor or Claude code, allowing you to assign tasks to agents, attend to other matters, and still receive progress updates and notifications when tasks are completed.

🚀 Quick Start

You need an OpenAI API key to use this server.

✨ Features

Available Tools

The server exposes the following tools:

• summarize(text: str): Converts the provided text to speech using OpenAI's TTS API and plays it to the user. Useful for providing status updates or confirming command execution.

📦 Installation

In Claude for Desktop

Add the voice-status-report directory to your Python path, for example:

export PYTHONPATH="${PYTHONPATH}:/path/to/voice-status-report"

💻 Usage Examples

Basic Usage

In Claude for Desktop

Update your claude_desktop_config.json (located at ~/Library/Application\ Support/Claude/claude_desktop_config.json on macOS and %APPDATA%/Claude/claude_desktop_config.json on Windows) to include the following:

{
  "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 a beep before each voice message. Disabled by default.
• --api-key: Specify the OpenAI API key. By default, it's retrieved from the environment variable OPENAI_API_KEY.
• --volume: Set the volume for playing the sound (between 0 and 1). Defaults to 1.0.

Examples

# Run the server with default settings
python3 -m voice_status_report_mcp_server

# Run the server with lower volume
python3 -m voice_status_report_mcp_server --volume 0.5

# Set a custom API key
python3 -m voice_status_report_mcp_server --api-key your_api_key_here

Advanced Usage

In Claude for Desktop

Edit or create the ~/.config/claude/claude_desktop_config.json file and add the following to enable voice reporting:

{
  "mcpServers": {
    "voice-status-report": {
      "command": "python3",
      "args": [
        "-m",
        "voice_status_report_mcp_server"
      ],
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Example Usage

After assigning a task:

from voice_status_report import summarize

summarize("Processing your request...")

After completing a task:

from voice_status_report import summarize

summarize("Task completed! Please check the results.")

📄 License

This project is released under the MIT License. See the LICENSE file for details.