Speech MCP Server for MacOS

This is a Model Context Protocol (MCP) server that provides text-to-speech capabilities using OmniVoice AI neural Voice Design and native macOS say. It allows AI agents (like Google Antigravity, Claude Desktop, Cursor, Windsurf, or Codex) to speak to you directly with unique, persona-tailored voices.

Note: This server is designed for macOS systems (with Apple Silicon MPS acceleration).

Explore the interactive web showcase and prompt compiler: https://fellowgeek.github.io/mcp-speak/ Browse the AI Agent Persona Catalog & Avatars: PERSONAS.md

Features

• OmniVoice Voice Cloning: Drop reference audio clips into voices/<persona>.wav to clone real vocal timbre and identity with zero configuration.

• OmniVoice Voice Design Fallback: Generates custom persona voices from natural language style prompts when no reference audio file is present.

• 3-Tier Robust Voice Pipeline: Seamlessly falls back: Cloned Voice (.wav) ➔ Voice Design (instruct) ➔ macOS native say.

• Consistent Neural Speech: Generates complete messages in a continuous synthesis pass for seamless, uniform vocal timbre and expression throughout.

• Interactive Setup Wizard: Run python3 setup.py to choose your TTS engine (OmniVoice or macOS say), select agent personas, and generate instruction files (AGENTS.md, GEMINI.md, CLAUDE.md, .cursorrules).

• Sequential Speech Queue: Strict FIFO queue ensures multiple non-blocking speech calls never talk over each other.

• Automatic Fallback: Seamlessly falls back to native macOS say if neural models cannot be loaded.

• Auto-Provisioning Virtual Environment: Uses run.sh to automatically create a local .venv (Python 3.12) and install dependencies.

• Blocking & Non-Blocking Support: Choose between waiting for speech to finish (speak) or continuing immediately (speak_non_blocking).

Related MCP server: Yak MCP

Prerequisites

• MacOS

• Python 3 installed

Quick Start (Interactive Setup)

1. Clone this repository or navigate to the project folder:

   git clone https://github.com/fellowgeek/mcp-speak.git
   cd mcp-speak

2. Run the interactive setup wizard (automatically configures MCP settings, sets permissions, and creates instruction files):

   python3 setup.py

Non-Interactive Setup (CLI Options)

You can also run setup.py with command-line flags for automated provisioning:

# Example: Configure all tools with OmniVoice on MPS using the Neutral Mainframe persona
python3 setup.py --non-interactive --tool 8 --engine omnivoice --device mps --persona neutral_mainframe --name "Mr. Reed"

# Example: Configure Cursor locally with macOS say and Sarcastic Senior
python3 setup.py --tool 4 --engine say --persona sarcastic_senior --local

Persona Voice Audition (test_personas.py)

Preview and compare persona vocal identities directly in the terminal before configuring your AI agent:

# Launch interactive terminal audition menu
python3 test_personas.py

# Audition a specific persona
python3 test_personas.py --persona agent_smith

# Audition all personas sequentially
python3 test_personas.py --all

# Test with custom speech text and specific engine
python3 test_personas.py --persona neutral_mainframe --engine omnivoice --text "System operational. All parameters within nominal thresholds."

# Audition an arbitrary WAV audio reference file for voice cloning
python3 test_personas.py --persona pun_master --voice-file voices/pun_master.wav

Neural Voice Cloning (voices/)

You can clone any persona's voice simply by dropping a 3-10 second .wav audio sample into the voices/ directory:

voices/
├── README.md
├── pun_master.wav         # Reference audio for pun_master
├── pun_master.txt         # (Optional) Transcript for faster startup without Whisper
├── nature_narrator.wav
└── agent_smith.wav

How the 3-Tier Voice Pipeline Works:

1. Tier 1 (Cloned Voice): If voices/<persona_name>.wav exists, OmniVoice clones the voice timbre from that recording.

2. Tier 2 (Voice Design): If no .wav file is present, OmniVoice falls back to the natural language instruct voice design prompt.

3. Tier 3 (macOS Native Fallback): If neural synthesis fails or is disabled, the server automatically speaks using macOS say.

Tip: Adding an optional transcript file (e.g. voices/pun_master.txt) with the exact spoken words in the audio allows OmniVoice to tokenize the reference audio immediately without needing to load or run the Whisper ASR model.

MCP Tool Interface Reference

The MCP Speak server exposes two tools via FastMCP:

Configuration & Environment Variables

The server loads configuration from config.json at startup:

{
  "engine": "omnivoice",
  "persona": "neutral_mainframe",
  "device": "auto",
  "voices_dir": "voices",
  "fallback_to_say": true
}

Environment Variable Overrides

Runtime parameters can be overridden via environment variables without modifying config.json:

• MCP_SPEAK_ENGINE: Set to "omnivoice" or "say".

• MCP_SPEAK_PERSONA: Set to any persona key (e.g. "agent_smith", "neutral_mainframe").

• MCP_SPEAK_DEVICE: Set to "auto", "mps", "cuda", or "cpu".

• MCP_SPEAK_VOICES_DIR: Set to a custom directory path containing reference audio files.

Client Integration

Manual Configuration (Optional)

If you prefer to configure your MCP client manually, add the "voice" server pointing to run.sh:

1. Google Antigravity (AGY)

Edit ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "voice": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

2. Claude CLI (Claude Code)

claude mcp add --scope user voice -- /ABSOLUTE/PATH/TO/run.sh

3. Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "voice": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

4. Cursor IDE

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "voice": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

5. Windsurf Editor

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "voice": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

6. Codex Desktop

Edit ~/.codex/config.toml:

[mcp_servers.voice]
command = "/ABSOLUTE/PATH/TO/run.sh"

7. Codex CLI

codex mcp add voice -- /ABSOLUTE/PATH/TO/run.sh

Agent Personalization & Personas

AI agents (Google Antigravity, Claude Code, Claude Desktop, Cursor, Windsurf, Codex) can be customized with unique vocal personalities, tones, and behavioral boundaries.

View the complete persona gallery, detailed system prompts, and avatar showcase in PERSONAS.md.

Available Personas Overview

How Prompts Are Built

Every agent prompt consists of:

1. Base Guidelines (personas/base_guidelines.md): Voice-first protocol and brevity constraints.

2. Chosen Persona (personas/): Personality quirks, tone, and strict execution boundaries.

3. Name Personalization (Optional): Addressing the user naturally by name.

Running python3 setup.py automatically generates and updates your agent instructions (AGENTS.md, GEMINI.md, CLAUDE.md, .cursorrules). For manual configuration steps, full system prompts, and avatars, see PERSONAS.md.

Optimizing Voice Quality

1. Neural Voice Synthesis with OmniVoice (Primary Engine)

OmniVoice delivers high-quality, expressive neural speech out of the box using style prompts tailored to each persona. To achieve the highest vocal fidelity:

• Neural Voice Cloning: Place a 3 to 10 second clean .wav audio sample in the voices/ directory matching the persona key (e.g. voices/sarcastic_senior.wav). OmniVoice clones the vocal timbre, tone, and inflection directly from the audio file without additional training.

• Fast Startup with Transcripts: Include an optional matching transcript text file (e.g. voices/sarcastic_senior.txt) containing the exact spoken text. This enables instant tokenization and skips loading the Whisper ASR model on startup.

• Audio Quality Guidelines: Use clean recordings without background noise, music, or heavy reverb. Standard WAV format sampled at 24kHz or higher is recommended.

• Voice Design Fallback: When no audio sample is present in voices/, OmniVoice uses natural language instructions (pitch, accent, speed, and character traits) configured in config.json.

2. macOS System Voice Configuration (Fallback Engine)

When using native macOS say (either as a fallback or in lightweight mode), voice quality depends on the active system voice. Configuring a modern Siri or Enhanced voice significantly improves realism and fluidity:

1. Open System Settings on your Mac.

2. Navigate to Accessibility > Spoken Content.

3. Click the System Voice dropdown menu.

4. Select Manage Voices....

5. Locate and download high-quality Siri voices (e.g., Siri Voice 1, 2, 3, 4) or voices marked as Enhanced / Premium (e.g., Ava, Evan, Zoe).

6. Set the downloaded voice as your default System Voice.

Note: Siri and Enhanced voices provide significantly more natural cadence, phrasing, and pronunciation compared to legacy system voices.

Testing & Validation

Run the automated test suite to verify configuration loading, engine fallbacks, single-pass synthesis, and sequential queue behavior:

# Run unit tests
python3 tests/test_speak_server.py

# Or run via unittest discovery in the virtual environment
.venv/bin/python -m unittest discover tests