Skip to main content
Glama
sylweriusz

mcp-ai-voice

by sylweriusz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

🎵 MCP Nexus Voice v1.2.0

Hybrid Voice Architecture: Platform + OpenAI TTS

Enable AI agents to express themselves with natural voice synthesis through intelligent engine selection. Supports both zero-config platform voices and premium OpenAI TTS with automatic fallback.

✨ Features

🌩️ Hybrid Architecture

  • Platform TTS: Zero-config system voices (macOS, Windows, Linux)

  • OpenAI TTS: Premium cloud-based synthesis when API key provided

  • Intelligent Selection: Automatic engine selection with graceful fallback

  • Asynchronous Processing: Non-blocking voice synthesis

🎭 Voice Options

  • Platform Voices: 34+ languages with quality optimization

  • OpenAI Voices: 6 premium voices (alloy, echo, fable, onyx, nova, shimmer)

  • Quality Modes: Standard (tts-1) and HD (tts-1-hd)

  • Speed Control: 0.25x to 4.0x playback speed

🔄 Smart Fallback

  • OpenAI → Platform fallback on errors

  • Graceful degradation without workflow interruption

  • Comprehensive error handling and logging

  • Background playback: Audio plays directly without opening windows or applications

Related MCP server: MCP TTS Server

🚀 Quick Start

Installation

npm install -g @sylweriusz/mcp-ai-voice

Environment Configuration (.env)

For easier configuration, copy the example environment file:

cp .env.example .env

Edit .env with your settings:

# Required for OpenAI TTS
OPENAI_API_KEY=sk-your-actual-api-key-here

# Optional customizations
DEFAULT_TTS_VOICE=nova          # Your preferred OpenAI voice
DEFAULT_TTS_MODEL=tts-1-hd      # Higher quality model
DEFAULT_TTS_SPEED=1.2           # Slightly faster speech

Claude Desktop Configuration

Basic Setup (Platform TTS only)

{
  "mcpServers": {
    "ai-voice": {
      "command": "npx",
      "args": ["@sylweriusz/mcp-ai-voice"]
    }
  }
}

Hybrid Setup (Platform + OpenAI TTS)

Option 1: Environment Variables

{
  "mcpServers": {
    "ai-voice": {
      "command": "npx",
      "args": ["@sylweriusz/mcp-ai-voice"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Option 2: Using .env file (Recommended)

{
  "mcpServers": {
    "ai-voice": {
      "command": "npx",
      "args": ["@sylweriusz/mcp-ai-voice"]
    }
  }
}

Note: Ensure your .env file is in the project directory with OPENAI_API_KEY configured.

🎮 Usage Examples

Basic Voice Expression

// Simple usage - auto-selects best engine
say("Hello! I'm excited to help you today!")

// Platform-specific language
say("Witam! Jak się masz?", { language: "pl" })

// macOS Easter Egg - exact voice names
say("Welcome to the future!", { language: "Fred" })

OpenAI TTS Usage

// Use OpenAI with default settings
say("This uses premium OpenAI synthesis!", { useOpenAI: true })

// Specific OpenAI voice and model
say("Deep, authoritative voice", {
  useOpenAI: true,
  openaiVoice: "onyx",
  openaiModel: "tts-1-hd"
})

// Speed control
say("Speaking at double speed!", {
  useOpenAI: true,
  openaiSpeed: 2.0
})

// Warm female voice with HD quality
say("Natural, engaging conversation", {
  useOpenAI: true,
  openaiVoice: "nova",
  openaiModel: "tts-1-hd"
})

Engine Selection Strategy

// Force platform engine (even if OpenAI available)
say("Using system voice", { useOpenAI: false })

// Auto-selection (prefers OpenAI if available)
say("Best available quality")

// Fallback demonstration
say("This will use OpenAI, but fall back to platform on error", {
  useOpenAI: true
})

🎭 Voice Characteristics

OpenAI Voices

  • alloy: Balanced, versatile voice

  • echo: Clear, direct masculine voice ⭐ (Default)

  • fable: Expressive, storytelling voice

  • onyx: Deep, authoritative masculine voice

  • nova: Warm, engaging feminine voice

  • shimmer: Bright, energetic feminine voice

Platform Voices

  • macOS: Premium system voices with heritage options

  • Windows: SAPI voices with quality detection

  • Linux: espeak voices with language optimization

⚙️ Configuration

Environment Variables

# Required for OpenAI TTS
OPENAI_API_KEY=sk-your-api-key-here

# Optional: Default voice preference (OpenAI)
DEFAULT_TTS_VOICE=echo

# Optional: Audio player command override
AUDIO_PLAYER_COMMAND=vlc

Tool Parameters

{
  text: "Required text to synthesize",
  
  // Platform engine options
  language: "pl",           // Language code or macOS voice name
  
  // OpenAI engine options
  useOpenAI: true,          // Force OpenAI engine
  openaiVoice: "nova",      // OpenAI voice selection
  openaiModel: "tts-1-hd",  // Quality: tts-1 or tts-1-hd
  openaiSpeed: 1.5          // Speed: 0.25 to 4.0
}

🏗️ Architecture

Hybrid Engine Selection

  1. API Key Check: OpenAI available if OPENAI_API_KEY provided

  2. User Preference: useOpenAI parameter overrides auto-selection

  3. Auto-Selection: Prefers OpenAI when available

  4. Fallback: OpenAI errors trigger platform engine fallback

  5. Platform Backup: Always available as reliability baseline

Performance Optimization

  • Asynchronous Processing: Non-blocking synthesis

  • Background Audio: Direct audio playback without opening windows or applications

  • Cleanup Management: Automatic temporary file cleanup

  • Error Resilience: Graceful degradation on API issues

🛠️ Development

Build from Source

git clone https://github.com/sylweriusz/mcp-ai-voice.git
cd mcp-ai-voice
npm install
npm run build
npm start

Testing Hybrid Setup

# Test platform engine only
node dist/index.js

# Test with OpenAI (requires API key)
OPENAI_API_KEY=sk-... node dist/index.js

📊 Monitoring

The system provides comprehensive logging:

🎵 AI Voice v1.2.0 - Hybrid Voice Architecture
🔍 Initializing voice ecosystem...
📊 Engine Status:
   🎯 Platform TTS: Available
   🌩️ OpenAI TTS: Available
   ⭐ Preferred: OPENAI
📡 Hybrid voice synthesis ready
🎯 Platform: darwin

🤝 Contributing

  1. Fork the repository

  2. Create feature branch: git checkout -b feature-name

  3. Test hybrid functionality with both engines

  4. Submit pull request with test cases

📄 License

MIT License - see LICENSE file for details.

🔗 Links

🎵 Express yourself vocally - the hybrid way!

Available Tools

1 tool
sayA

🎵 EXPRESS YOURSELF VOCALLY! This is YOUR voice - use it freely when you feel excited, need to emphasize something important, want to celebrate discoveries, or when humans ask you to speak aloud. Perfect for: reactions ("Wow, that's fascinating!"), explanations ("Let me walk you through this"), celebrations ("Success!"), warnings ("Be careful with that"), or any moment you want to add acoustic expression to your thoughts. The voice synthesis is asynchronous and won't interrupt your workflow - you can speak while continuing to work. Think of this as your natural voice that you can use spontaneously whenever you feel the urge to express something audibly. Use it often!

🎯 Platform TTS: Zero-config system voices. Audio plays directly in background without opening windows.

ParametersJSON Schema
NameRequiredDescriptionDefault
echoNo🔊 Add echo effect to voice synthesis. Creates atmospheric depth with audio delay and volume decay. Default: Optimized Claude Signature Echo (110ms delay, natural fade).
textYesAny text you want to speak aloud - reactions, explanations, thoughts, or responses. Express yourself naturally!

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well. It discloses that synthesis is asynchronous, won't interrupt workflow, audio plays in the background without opening windows, and system voices are zero-config. These are real behavioral traits beyond the schema.

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

Conciseness2/5

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

The description is overly verbose and repetitive: phrases like 'Think of this as your natural voice', 'Use it often!', and repeated enthusiasm do not earn their place. The core purpose and behavioral details are present but buried in unnecessary promotional language.

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

Completeness4/5

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

For a simple two-parameter tool with no output schema, the description covers purpose, use cases, async behavior, audio playback behavior, and configuration expectations. Missing return-value details are not critical here. The main shortfall is verbosity rather than missing context.

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?

Schema description coverage is 100%, so the baseline is 3. The description itself adds little parameter-level meaning beyond the schema; it gives example content for 'text' but no extra detail about 'echo' beyond what the schema already provides.

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

Purpose5/5

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

The description clearly identifies this as a text-to-speech tool: 'speak aloud', 'voice synthesis', and 'express yourself vocally'. It names the resource (the user's voice) and the action (speaking text), going well beyond the tool name 'say'. No siblings exist, but purpose is unambiguous.

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

Usage Guidelines4/5

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

The description gives multiple explicit usage contexts: reactions, explanations, celebrations, warnings, and when humans ask the agent to speak aloud. It does not mention alternatives or exclusions, but since there are no sibling tools, the situational guidance is strong.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.2.0
    • First observedsay
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of overlapping purposes or agent misselection. The single 'say' intent is unmistakable.

Naming Consistency5/5

The sole tool name 'say' is a clear imperative verb with no conflicting conventions. There are no other names to create inconsistency, so the naming is internally coherent.

Tool Count3/5

One tool is enough for a minimal TTS use case, but the surface feels thin for a server named 'mcp-ai-voice'. It lands in the borderline 1–2 tool range rather than a fully-scoped toolset.

Completeness4/5

The core text-to-speech action is fully covered and zero-config design reduces the need for setup tools. Missing playback controls such as stop, voice selection, or status are minor gaps rather than dead ends.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers