Skip to main content
Glama
orishu

MCP Voice Notification

by orishu
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

MCP Voice Notification

An MCP server that provides voice notifications using the Grok Voice API. Perfect for alerting you when Claude Code has finished a task.

Features

  • Text-to-speech voice notifications via Grok's realtime voice API

  • Works with Claude Code and other MCP-compatible clients

  • Two server modes: HTTP (streamable) or stdio (local)

  • Cross-platform audio playback (macOS, Linux)

Related MCP server: Claude Code Notification Hooks

Prerequisites

  • uv (Python package manager)

  • A Grok API key from x.ai

  • Audio playback capability (afplay on macOS, aplay/paplay on Linux)

Installation

  1. Clone the repository:

    git clone https://github.com/orishu/mcp-voice-notif.git
cd mcp-voice-notif

  2. Install dependencies with uv:

    uv sync

  3. Set up your environment:

    cp env.sample .env
# Edit .env and add your GROK_API_KEY

Usage

Option 1: Stdio Server (Recommended for local use)

The stdio server communicates via standard input/output, which is the simplest setup for local MCP clients.

Using the claude mcp add command (Recommended)

The easiest way to add the server is using the Claude Code CLI:

claude mcp add voice-notification -e GROK_API_KEY=your_api_key_here -- \
  uv run --directory /path/to/mcp-voice-notif python stdio_server.py

Replace /path/to/mcp-voice-notif with the actual path to this project.

Manual configuration

Alternatively, add to your Claude Code MCP configuration (~/.claude/claude_code_config.json):

{
  "mcpServers": {
    "voice-notification": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-voice-notif", "python", "stdio_server.py"],
      "env": {
        "GROK_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option 2: HTTP Server (For remote/shared use)

The HTTP server runs as a persistent service, useful for remote access or shared setups.

  1. Start the server:

    uv run python server.py

    The server will start on http://127.0.0.1:8000.

  2. Add to your Claude Code MCP configuration:

    {
  "mcpServers": {
    "voice-notification": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Tool Reference

voice_notification

Generates and plays a voice notification.

Parameters:

  • text (string, optional): The text to speak. Default: "Done!"

Example responses:

  • "Voice notification played: 'Build complete!'"

  • "No audio data received from API"

Configuring Claude Code to Use Voice Notifications

To have Claude Code automatically notify you when it's ready for your next prompt, add the following to your project's CLAUDE.md file (or global ~/.claude/CLAUDE.md):

When you complete a task, use the voice_notification tool to alert the user.
Keep the message short and contextual (e.g., "Build done!", "Tests passed!", "Ready!").

This instructs the agent to call the voice notification with a brief, task-relevant message whenever it finishes working.

Testing

To test the voice API directly:

uv run python test_voice_api.py

License

MIT License - see LICENSE for details.

Available Tools

1 tool
voice_notificationC

Generate a voice notification using Grok Voice API and play it.

Args: text: The text to convert to speech (default: "Done!")

Returns: str: Confirmation message

ParametersJSON Schema
NameRequiredDescriptionDefault
textNoDone!

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions the action ('generate and play') but fails to disclose critical behavioral traits like authentication requirements, rate limits, side effects (e.g., audio playback), or error handling. This is a significant gap for a tool that interacts with an external API and produces audio output.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, Args, Returns) and uses minimal sentences. It avoids redundancy, though the 'Args' and 'Returns' labels are slightly verbose; overall, it's efficient and front-loaded with the main action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (API interaction, audio output) and no annotations, the description is incomplete—it lacks behavioral details and usage context. However, the presence of an output schema (explaining the return value) mitigates some gaps, making it minimally adequate but with clear room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description includes an 'Args' section that explains the 'text' parameter as 'The text to convert to speech', adding meaning beyond the input schema (which has 0% description coverage and only defines type and default). However, it doesn't elaborate on constraints (e.g., length, language) or provide examples, so it partially compensates but not fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Generate a voice notification using Grok Voice API and play it.' This specifies the verb ('generate and play'), resource ('voice notification'), and technology ('Grok Voice API'). However, with no sibling tools, differentiation is not applicable, preventing a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, prerequisites, or context. It lacks any usage instructions, such as when voice notifications are appropriate or what scenarios it's designed for, leaving the agent without operational context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.1/5.0
Disambiguation5/5

With only one tool, there is no possibility of confusion or overlap between tools. The tool's purpose is clearly defined and distinct by default.

Naming Consistency5/5

The single tool name 'voice_notification' follows a clear verb_noun pattern. Since there is only one tool, consistency is inherently perfect with no deviations to assess.

Tool Count2/5

One tool is too few for a server named 'MCP Voice Notification', which suggests broader voice-related capabilities. A single tool for generating and playing notifications feels thin and limited in scope, lacking operations like listing, managing, or customizing notifications.

Completeness2/5

The server's domain appears to be voice notifications, but the tool surface is severely incomplete. It only covers generating and playing a single notification, with no support for operations like listing notifications, updating settings, handling errors, or managing multiple notifications, which are typical for such a domain.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Claude Code Notification Hooks

    nkyy
    A
    license
    A
    quality
    D
    maintenance
    Provides automatic desktop notifications and contextual sounds for Claude Code operations across macOS, Windows, and Linux. It enhances the development experience by intelligently mapping specific event types to native system alerts and sounds.
    4
    11
    3
    MIT

  • claude-voice-notify

    kubouchiyuya
    A
    license
    Not graded
    quality
    D
    maintenance
    A multi-provider voice notification MCP server that enables Claude Code to provide auditory alerts for task completions, confirmation requests, and errors. It supports various TTS engines including VOICEVOX, Google Cloud TTS, and OpenAI for customizable voice feedback.
    3
    1
    MIT

  • notify-mcp

    ShikeChen01
    A
    license
    Not graded
    quality
    D
    maintenance
    Sends native Windows desktop notifications with repeating sound alerts for Claude Code, supporting states like finished, needs_help, and pending_review.
    74
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/orishu/mcp-voice-notif'

If you have feedback or need assistance with the MCP directory API, please join our Discord server