mcp-tts 0.2.0

MCP Text-to-Speech Server for Cursor IDE (and others) with cross-platform audio playback

MCP Text-to-Speech Server for Cursor IDE

A cross-platform MCP (Model Context Protocol) server that provides text-to-speech capabilities for Cursor IDE, allowing AI assistants to provide audio summaries and speech output through local speakers.

✅ Current Status

Working Features:

• ✅ MCP Server - 6 tools registered and working with Cursor
• ✅ Web Configuration Interface - Voice presets, device selection, settings management
• ✅ OpenAI TTS Integration - Using gpt-4o-mini-tts with custom voice instructions
• ✅ Cross-platform Audio - 49 audio devices detected, playback working
• ✅ Voice Presets - 9 presets including professional, NYC cabbie, chill surfer styles
• ✅ Persistent Configuration - Settings saved between sessions

🚀 Quick Start

Option 1: uvx Installation (Recommended for End Users)

The easiest way to use this server is through uvx, which automatically handles installation and dependencies:

Prerequisites:

• uv package manager (for uvx)
• OpenAI API key
• Cursor IDE

Setup: Just add this to your Cursor MCP configuration - no cloning or setup required!

Note: The package provides two executables:

• mcp-tts-server-stdio - For MCP/Cursor integration (what you want)
• mcp-tts-server - For standalone web interface

Option 2: Local Development Setup

For development or if you want to modify the code:

Prerequisites:

• Python 3.11+
• uv package manager
• OpenAI API key
• Cursor IDE

Installation:

1. Clone and setup:

   git clone <your-repo>
   cd mcp-cursor-tts
   

2. Install dependencies:

   uv sync
   

3. Configure environment:

   cp env.example .env
   # Edit .env and add your OPENAI_API_KEY
   

Running the Servers

🎵 MCP Server (for Cursor integration)

# Using the batch file (recommended for Windows)
start-mcp-tts.bat

# Or directly
uv run python src/mcp_server.py

🌐 Web Configuration Server

# Start web interface
uv run python src/main.py

# Then visit: http://localhost:8742

🔌 Cursor Integration

MCP Configuration

Add this to your Cursor MCP settings file (~/.cursor/mcp.json):

Option 1 (Recommended - Using uvx):

{
  "mcpServers": {
    "mcp_tts_server": {
      "command": "uvx",
      "args": ["--from", "mcp-cursor-tts", "mcp-tts-server-stdio"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Option 2 (Local development - Using batch file):

{
  "mcpServers": {
    "mcp_tts_server": {
      "command": "C:/repos/mcp-cursor-tts/start-mcp-tts.bat"
    }
  }
}

Option 3 (Local development - Direct command):

{
  "mcpServers": {
    "mcp_tts_server": {
      "command": "uv",
      "args": ["--directory", "C:/repos/mcp-cursor-tts", "run", "python", "src/mcp_server.py"],
      "env": {}
    }
  }
}

Important for local options: Update the path C:/repos/mcp-cursor-tts to match your actual project location.

Available MCP Tools

Once connected to Cursor, you'll have access to these 6 tools:

• 🎵 text_to_speech - Convert text to speech with customizable voices and styles
• 🔊 list_audio_devices - Show available audio output devices
• 🧪 test_audio_device - Test audio device with a tone
• ⏹️ stop_speech - Stop current audio playback
• 📊 get_tts_status - Get server status and configuration
• 🔈 set_volume - Adjust playback volume

Example Usage in Cursor

Try asking your AI assistant:

• "Can you read me a summary of the changes you just made using text-to-speech with a professional voice?"
• "List my available audio devices"
• "Use the NYC cabbie voice style to explain this code"

⚙️ Configuration

Voice Presets

The server includes 9 voice style presets:

• Default - Clear, friendly, and conversational
• Professional - Authoritative business voice
• Calm - Composed, reassuring with quiet authority
• NYC Cabbie - Fast-talking New Yorker with edge
• Chill Surfer - Laid-back, mellow, effortlessly cool
• Cheerleader - High-energy, enthusiastic, motivational
• Emo Teenager - Sarcastic, disinterested, melancholic
• Eternal Optimist - Positive, solution-oriented
• Dramatic - Low, hushed, suspenseful with theatrical flair

Web Interface

Visit http://localhost:8742 for:

• Voice and audio device configuration
• Voice preset selection and custom instructions
• Real-time testing and preview
• Settings persistence

📁 Project Structure

mcp-cursor-tts/
├── src/
│   ├── mcp_server.py          # FastMCP server (for Cursor)
│   ├── main.py               # Web configuration server
│   ├── config.py             # Configuration management
│   ├── api/
│   │   └── routes.py         # FastAPI routes
│   ├── tts/
│   │   ├── manager.py        # TTS coordination
│   │   └── providers/
│   │       ├── base.py       # Provider interface
│   │       └── openai_fm.py  # OpenAI FM API implementation
│   └── audio/
│       ├── player.py         # Cross-platform audio playback
│       └── devices.py        # Audio device enumeration
├── tests/                    # All test files
├── config/
│   ├── default.yaml          # Default configuration
│   └── user_settings.json    # Persistent user settings
├── static/                   # Web UI assets
├── start-mcp-tts.bat         # Windows startup script
└── .env                      # Environment variables

🧪 Testing

Run the test suite:

# Test MCP server functionality  
uv run python tests/test_fastmcp.py

# Test TTS functionality
uv run python tests/demo_tts.py

# Test web API
uv run python tests/test_server.py

🔧 Development Commands

# Start MCP server for Cursor
uv run python src/mcp_server.py

# Start web interface for configuration  
uv run python src/main.py

# Test basic functionality
uv run python tests/test_fastmcp.py

# Test TTS with real audio
uv run python tests/demo_tts.py

# Check health
curl http://localhost:8742/api/health

🐛 Troubleshooting

Common Issues

"0 tools enabled" in Cursor:

• ✅ Fixed! - Updated to use modern FastMCP API
• Ensure you're using the correct batch file path
• Restart Cursor after updating MCP configuration

"Module not found" errors:

• ✅ Fixed! - All import conflicts resolved
• Make sure you're using uv run commands

Audio not working:

• Check available devices: visit http://localhost:8742/api/devices
• Test audio device via web interface
• Verify OpenAI API key in .env file

Server won't start:

• Check port 8742 isn't in use: netstat -an | findstr 8742
• Verify all dependencies installed: uv sync

Recent Fixes Applied

• ✅ Migrated from old MCP API to FastMCP
• ✅ Fixed import conflicts (mcp/ → mcp_old/)
• ✅ Updated all relative imports to absolute imports
• ✅ Organized test files into tests/ directory
• ✅ Fixed batch file to use correct server path

📚 API Documentation

With the web server running, visit:

• Main interface: http://localhost:8742
• API docs: http://localhost:8742/docs
• Health check: http://localhost:8742/api/health

📦 Publishing to PyPI

To make this package available via uvx for all users:

1. Update package metadata:

   # Edit pyproject.toml with your details:
   # - author name/email
   # - repository URLs
   # - version number
   

2. Build the package:

   uv build
   

3. Publish to PyPI:

   # Install twine if needed
   uv add --dev twine
   
   # Upload to PyPI (you'll need PyPI credentials)
   uv run twine upload dist/*
   

4. Test the published package:

   uvx --from mcp-cursor-tts mcp-tts-server-stdio
   

Once published, users can use the simple uvx configuration shown above!

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: uv run python tests/test_fastmcp.py
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

---

🎉 Status: Fully Functional! The MCP TTS server is working correctly with Cursor IDE. All 6 tools are registered and accessible through natural language interaction.