Labsco
FiveOhhWon logo

Summarize MCP

★ 1

from FiveOhhWon

Converts text summaries to speech using OpenAI's Text-to-Speech API and plays them in the background.

🔥🔥✓ VerifiedAccount requiredNeeds API keys
#automation#ai-video#voice#git#video-editing

summarize-mcp

🤖 Co-authored with Claude Code - Making AI summaries audible since 2025! 🔊

A Model Context Protocol (MCP) server that converts text summaries to speech using OpenAI's TTS API and plays them in the background across all major platforms (macOS, Windows, Linux).

🌟 Overview

summarize-mcp enables LLMs to convert any text summary into natural-sounding speech using OpenAI's state-of-the-art text-to-speech models. Perfect for creating audio summaries of documents, articles, or any content that benefits from an auditory presentation.

🚀 Key Features

  • 🎯 Simple & Focused: One tool that does one thing exceptionally well
  • 🎤 Multiple Voices: Choose from 10 distinct OpenAI voices (alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer)
  • 🎨 Custom Instructions: Control how the text should be spoken
  • 🔧 Background Playback: Audio plays in the background without blocking
  • 🌍 Cross-Platform: Works on macOS, Windows, and Linux
  • 💾 Persistent Preferences: Save your favorite voice and tone settings
  • 🎯 Multiple Tools: Set voice, set tone, and play summaries
  • 🧹 Automatic Cleanup: Temporary files are cleaned up automatically
  • 🛡️ Type-Safe: Full Python type hints with Pydantic validation
  • 📊 Comprehensive Logging: Debug mode for troubleshooting
  • ⚡ Performance Optimized: Efficient file handling and cleanup

🛠️ Available Tools

play_summary

Converts text to speech and plays it in the background. Uses saved voice and tone preferences unless overridden.

Parameters:

  • summary (required): The text to convert to speech
  • voice (optional): Voice to use - alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, or shimmer (uses saved preference if not specified)
  • instructions (optional): Instructions for how the text should be spoken (uses saved tone if not specified)

Example:

{
  "summary": "The quick brown fox jumps over the lazy dog. This pangram contains all letters of the alphabet.",
  "voice": "nova",
  "instructions": "Speak slowly and clearly, emphasizing each word."
}

set_voice

Set the default voice for all future text-to-speech conversions.

Parameters:

  • voice (required): The voice to use - alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, or shimmer

Example:

{
  "voice": "nova"
}

set_tone

Set the default tone/instructions for how text should be spoken in all future TTS requests.

Parameters:

  • tone (required): The tone/instructions to use (e.g., "Speak slowly and calmly", "Be enthusiastic and energetic")

Example:

{
  "tone": "Speak in a warm, friendly manner with moderate pacing"
}

🎯 Voice Options

VoiceDescription
alloyNeutral and balanced
ashWarm and engaging
balladExpressive and dramatic
coralClear and professional (default)
echoSmooth and reflective
fableExpressive and animated
novaFriendly and upbeat
onyxDeep and authoritative
sageWise and measured
shimmerSoft and gentle

🧪 Development

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Run the server
python -m summarize_mcp

# Run tests
python test.py

# Run with debug logging
DEBUG=true python -m summarize_mcp

🏗️ Architecture

summarize-mcp/
├── src/
│   └── summarize_mcp/
│       ├── __init__.py      # Package initialization
│       ├── __main__.py      # Entry point for python -m
│       └── server.py        # Main MCP server implementation
├── pyproject.toml           # Python project metadata
├── requirements.txt         # Python dependencies
├── test.py                  # Test script
└── README.md               # This file

🔧 Technical Details

  • Audio Format: MP3 (OpenAI TTS output format)
  • Temporary Files: Stored in system temp directory
  • File Cleanup: Automatic cleanup after 10 seconds (configurable)
  • Old File Purge: Files older than 1 hour are cleaned on startup
  • Platform Support:
    • macOS: Uses built-in afplay
    • Windows: Uses PowerShell with Windows Media Player
    • Linux: Auto-detects available player (mpg123, sox, ffmpeg, vlc, alsa)
    • Fallback: Opens with system default audio application
  • State Management:
    • Preferences saved to ~/.summarize-mcp-state.json
    • Persists voice and tone settings between sessions
    • Automatic loading on startup
  • Error Handling: Comprehensive error handling with specific error types
  • Validation: Input validation using Pydantic models

📝 Changelog

v2.0.0 (Python Rewrite)

  • 🐍 Complete rewrite in Python for better cross-platform support
  • 🔧 Improved async handling with Python's asyncio
  • 📦 Simplified installation with pip
  • 🛡️ Enhanced type safety with Pydantic
  • 🚀 Better performance and reliability

v1.2.0 (Persistent Preferences)

  • 💾 Added persistent state management for voice and tone preferences
  • 🎯 Added set_voice tool to set default voice
  • 🎯 Added set_tone tool to set default speaking instructions
  • 🎆 Added support for new OpenAI voices: ash, ballad, and sage
  • 🔄 play_summary now uses saved preferences unless overridden
  • 📝 State saved to ~/.summarize-mcp-state.json

v1.1.0 (Cross-Platform Support)

  • 🌍 Added Windows support using PowerShell/Windows Media Player
  • 🐧 Added Linux support with auto-detection of audio players
  • 🔄 Added fallback to system default audio player
  • 📝 Updated documentation for multi-platform usage

v1.0.0 (Initial Release)

  • 🎉 Initial release
  • ✨ Core TTS functionality with OpenAI integration
  • ✨ Support for 7 different voices
  • ✨ Custom speaking instructions
  • ✨ Background audio playback on macOS
  • ✨ Automatic file cleanup
  • ✨ TypeScript implementation
  • ✨ Comprehensive error handling

💰 Estimated Costs

This tool uses OpenAI's gpt-4o-mini-tts model for text-to-speech conversion. Here's the pricing breakdown:

ModelAudio Output PriceEstimated Cost
gpt-4o-mini-tts$12.00 per 1M tokens$0.015 per minute of audio

Cost Examples:

  • 100-word summary (~30 seconds): ~$0.0075
  • 500-word summary (~2.5 minutes): ~$0.0375
  • 1000-word summary (~5 minutes): ~$0.075

The actual cost depends on:

  • Length of your summaries
  • Speaking speed (instructions can affect this)
  • How frequently you use the tool

For current pricing details, see OpenAI's pricing page.

🔮 Roadmap

  • Cross-platform audio playback (Windows, Linux)
  • Python implementation for better cross-platform support
  • Additional TTS providers (ElevenLabs, Amazon Polly)
  • Audio format options (WAV, OGG)
  • Playback control (pause, resume, stop)
  • Queue management for multiple summaries
  • Audio file caching
  • Speed and pitch controls
  • SSML support for advanced speech control

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments