j3k0/speech.sh

A text-to-speech CLI and MCP server using the Groq TTS API (OpenAI-compatible).
Features
- Convert text to speech with a simple command
- Multiple voice options (troy, austin, hannah, autumn)
- Adjustable speech speed
- Hash-based caching to avoid duplicate API calls (24h auto-cleanup)
- Retry with exponential backoff
- Audio playback via ffplay, mplayer, or VLC
- MCP server for integration with AI assistants (Claude Desktop, Claude Code)
Quick Start
Dependencies
- curl, jq (for the shell version)
- One audio player: ffplay (from ffmpeg), mplayer, or vlc
CLI Usage
Options
API Key
Provide your Groq API key in one of three ways (in order of precedence):
1. --api_key "your-key"
2. export OPENAI_API_KEY="your-key"
3. A file named API_KEY in the script's directory
MCP Server
Two implementations are available:
Python (recommended)
Uses the FastMCP SDK. Requires Python 3.10+ and uv.
Claude Desktop / Claude Code configuration
Shell (legacy)
The original shell-based MCP server (mcp.sh). Works in environments without Python but may hit macOS sandboxing issues with Claude Desktop.
MCP Tool
The server exposes a single speak tool:
| Parameter | Type | Required | Default | Description |
|-----------|--------|----------|---------|--------------------------|
| text | string | yes | | The text to speak |
| voice | string | no | troy | Voice to use |
| speed | number | no | 1.0 | Speech speed |
Environment Variables
| Variable | Description | Default |
|------------------|------------------------|----------------------------------|
| OPENAI_API_KEY | Groq API key | (required) |
| SPEECH_VOICE | Default voice | troy |
| SPEECH_SPEED | Default speed | 1.0 |
| SPEECH_MODEL | TTS model | canopylabs/orpheus-v1-english |
| SPEECH_API_URL | API endpoint (Python) | https://api.groq.com/openai/v1/audio/speech |
Architecture
- **speech.sh** - Shell-based TTS engine (API calls, caching, playback)
- **mcp.sh** - Shell-based MCP wrapper over speech.sh (JSON-RPC 2.0 over stdio)