{"id":45963495,"url":"https://github.com/alamparelli/mcp-claude-say","last_synced_at":"2026-02-28T14:01:33.300Z","repository":{"id":332365035,"uuid":"1132308298","full_name":"alamparelli/mcp-claude-say","owner":"alamparelli","description":"Voice interaction for Claude Code - Talk to Claude and hear responses using macOS speech synthesis and Parakeet MLX","archived":false,"fork":false,"pushed_at":"2026-01-29T21:17:51.000Z","size":6506,"stargazers_count":7,"open_issues_count":5,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-30T08:56:15.002Z","etag":null,"topics":["apple","claude-code","conversation","mcp","silicon","speech-to-text","stt","text-to-speech","tts","voice"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alamparelli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-11T18:05:57.000Z","updated_at":"2026-01-29T20:57:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alamparelli/mcp-claude-say","commit_stats":null,"previous_names":["alamparelli/mcp-claude-say"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alamparelli/mcp-claude-say","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alamparelli%2Fmcp-claude-say","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alamparelli%2Fmcp-claude-say/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alamparelli%2Fmcp-claude-say/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alamparelli%2Fmcp-claude-say/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alamparelli","download_url":"https://codeload.github.com/alamparelli/mcp-claude-say/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alamparelli%2Fmcp-claude-say/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29936351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T13:49:17.081Z","status":"ssl_error","status_checked_at":"2026-02-28T13:48:50.396Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple","claude-code","conversation","mcp","silicon","speech-to-text","stt","text-to-speech","tts","voice"],"created_at":"2026-02-28T14:00:53.961Z","updated_at":"2026-02-28T14:01:33.268Z","avatar_url":"https://github.com/alamparelli.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-claude-say\n\n\u003e **macOS only** - Uses native macOS speech synthesis and Parakeet MLX for STT\n\nVoice interaction MCP servers for Claude Code. Includes both Text-to-Speech (TTS) and Speech-to-Text (STT) for a complete voice conversation experience.\n\n## Features\n\n- **Voice responses** - Claude speaks its responses aloud\n- **Voice input** - Talk to Claude using Push-to-Talk (PTT)\n- **Full conversation mode** - Complete voice loop with `/conversation`\n- **Fast local STT** - Uses Parakeet MLX (optimized for Apple Silicon)\n- **Multilingual** - Speaks and understands multiple languages\n- **Lightweight** - Uses native macOS speech synthesis by default, no external APIs\n\n## TTS Backend Options\n\nChoose your TTS backend based on your needs:\n\n| Backend | Quality | Storage | Latency | Free Tier |\n|---------|---------|---------|---------|-----------|\n| **macOS** (default) | Basic | 0 | Instant | Unlimited |\n| **Google Cloud** | Good | 0 | ~0.5s | 1M chars/mo |\n| **Chatterbox** | Excellent | 11GB | ~0.3s | Unlimited |\n\n### Option 1: macOS (Default)\n\nNo setup required. Uses the native `say` command. Voice is robotic but works everywhere.\n\n### Option 2: Google Cloud TTS (Recommended)\n\nNatural-sounding voices with zero storage footprint.\n\n**Pricing Tiers:**\n\n| Tier | Quality | Price |\n|------|---------|-------|\n| Neural2 | Good | Free (1M chars/mo) |\n| Studio | Better | $0.16/1M chars |\n| Journey | Conversational | $0.30/1M chars |\n| Chirp3-HD | Best (Gemini) | $0.30/1M chars |\n\n**Setup:**\n\n1. Create a Google Cloud project at [console.cloud.google.com](https://console.cloud.google.com)\n2. Enable the [Text-to-Speech API](https://console.cloud.google.com/apis/library/texttospeech.googleapis.com)\n3. Create an API key at [APIs \u0026 Services \u003e Credentials](https://console.cloud.google.com/apis/credentials)\n\n**Configure via installer (recommended):**\n\nRun `./install.sh` and select \"Google Cloud TTS\" when prompted. The installer will guide you through entering your API key and selecting a voice.\n\n**Or configure manually:**\n\nEdit `~/.mcp-claude-say/.env`:\n\n```bash\nTTS_BACKEND=google\nGOOGLE_CLOUD_API_KEY=your-api-key-here\nGOOGLE_VOICE=en-US-Neural2-F\nGOOGLE_LANGUAGE=en-US\n```\n\nThen restart Claude Code.\n\n**Example Voices:**\n\n| Voice | Tier | Description |\n|-------|------|-------------|\n| `en-US-Neural2-F` | Free | US female (default) |\n| `en-US-Journey-O` | Paid | US female, conversational |\n| `en-GB-Chirp3-HD-Erinome` | Paid | British female |\n| `en-GB-Chirp3-HD-Aoede` | Paid | British female |\n| `en-US-Neural2-D` | Free | US male |\n\nSee [all voices](https://cloud.google.com/text-to-speech/docs/voices) for more options.\n\n### Option 3: Chatterbox (Local Neural TTS)\n\nHighest quality, runs 100% locally, but requires 11GB storage for model weights.\n\n**Setup:**\n\n```bash\n# Requires Python 3.11 (Chatterbox doesn't support 3.12+)\npython3.11 -m venv ~/.mcp-claude-say/venv-tts\nsource ~/.mcp-claude-say/venv-tts/bin/activate\npip install chatterbox-tts uvicorn fastapi torchaudio\n\n# Add a voice sample (5-10 seconds of clear speech, 24kHz WAV)\nmkdir -p ~/.mcp-claude-say/voices\n# Copy your sample to voices/female_voice.wav\n```\n\n**Configure:**\n\n```bash\nexport TTS_BACKEND=\"chatterbox\"\n```\n\n**Usage:**\n\nThe Chatterbox service must be started manually:\n\n```bash\n# Start the service (~5-10 sec to load model)\n~/.mcp-claude-say/start_tts_service.sh\n\n# Verify it's running\ncurl http://127.0.0.1:8123/health\n\n# Stop when done (frees ~1.5GB RAM)\n~/.mcp-claude-say/stop_tts_service.sh\n```\n\n| Factor | Impact |\n|--------|--------|\n| Storage | ~11GB for model weights |\n| RAM | ~1.5GB when running |\n| First load | 5-10 seconds |\n\nIf the service isn't running, TTS falls back to macOS `say`.\n\n## One-Line Installation\n\n```bash\ngit clone https://github.com/alamparelli/mcp-claude-say.git \u0026\u0026 cd mcp-claude-say \u0026\u0026 ./install.sh\n```\n\nOr if you've already cloned the repo:\n\n```bash\n./install.sh\n```\n\nThe interactive installer will guide you through:\n1. **STT backend selection** - Parakeet MLX or Apple SpeechAnalyzer\n2. **TTS backend selection** - macOS say or Google Cloud TTS\n3. **Google Cloud setup** (if selected) - API key and voice selection\n\n### What the installer does\n\n1. Creates a Python virtual environment\n2. Installs dependencies (MCP, Parakeet MLX, sounddevice, pynput)\n3. **Creates `~/.mcp-claude-say/.env`** with your TTS configuration\n4. Installs two skills: `/speak` and `/conversation`\n5. Configures both MCP servers in Claude Code settings\n\n### Configuration File\n\nAfter installation, your TTS settings are stored in `~/.mcp-claude-say/.env`:\n\n```bash\n# TTS Backend: macos, google\nTTS_BACKEND=macos\n\n# Google Cloud TTS settings (only used if TTS_BACKEND=google)\nGOOGLE_CLOUD_API_KEY=your-api-key\nGOOGLE_VOICE=en-US-Neural2-F\nGOOGLE_LANGUAGE=en-US\n```\n\nEdit this file and restart Claude Code to change settings. See `env.template` for all options.\n\n### CLI Options\n\nFor scripted/automated installation:\n\n```bash\n# Install with macOS TTS (default)\n./install.sh --parakeet --tts-macos\n\n# Install with Google Cloud TTS\n./install.sh --parakeet --tts-google --google-api-key \"YOUR_API_KEY\"\n\n# TTS only mode (no STT)\n./install.sh --tts-only --tts-google\n```\n\n## Usage\n\nAfter installation, restart Claude Code.\n\n### Voice Mode (TTS only)\n\n```\n/speak\n```\n\nClaude will speak its responses aloud.\n\n### Conversation Mode (TTS + STT)\n\n```\n/conversation\n```\n\nFull voice loop with automatic turn-taking:\n1. Press **Right Command** to start recording\n2. Speak your message\n3. Recording stops automatically when you finish speaking (VAD)\n4. Claude transcribes and responds vocally\n5. Recording restarts automatically after Claude finishes\n6. Continue the conversation naturally!\n\n**Barge-in:** Press **Right Command** anytime to interrupt Claude mid-sentence.\n\nSay **\"fin de session\"** to end the conversation.\n\n## Push-to-Talk Keys\n\n| Key | Description |\n|-----|-------------|\n| `cmd_r` | Right Command (default, recommended) |\n| `cmd_l+s` | Left Command + S |\n| `cmd_r+m` | Right Command + M |\n| `alt_l`, `alt_r` | Option keys |\n| `f13`, `f14`, `f15` | Function keys |\n\n### MacBook Hotkey Notes\n\nSome hotkeys don't work well on MacBooks:\n\n| Hotkey | Issue |\n|--------|-------|\n| `alt_l+c` | ❌ Produces `ç` character on macOS |\n| `f13`, `f14`, `f15` | ❌ MacBooks don't have these keys |\n| `ctrl_r` | ❌ MacBooks don't have Right Control |\n| `cmd_l+s` | ⚠️ Conflicts with Save in most apps |\n| `cmd_r` | ✅ Right Command alone - no conflicts, works everywhere |\n\n**Recommendation:** Use `cmd_r` (Right Command) for PTT on MacBooks.\n\n## Requirements\n\n- **macOS** (uses native `say` command + Parakeet MLX)\n- **Apple Silicon** recommended for fast STT\n- **Python 3.9+**\n- **Claude Code** CLI\n\n## MCP Servers\n\nThe installer configures two MCP servers:\n\n### claude-say (TTS)\n\n| Tool | Description |\n|------|-------------|\n| `speak(text, voice?, speed?)` | Queue text to speak |\n| `speak_and_wait(text, voice?, speed?)` | Speak and wait for completion |\n| `stop_speaking()` | Stop and clear queue |\n\n### claude-listen (STT)\n\n| Tool | Description |\n|------|-------------|\n| `start_ptt_mode(key?)` | Start Push-to-Talk mode |\n| `stop_ptt_mode()` | Stop PTT mode |\n| `get_ptt_status()` | Get current status |\n| `get_segment_transcription()` | Get transcribed text |\n\n## File Structure\n\n```\n~/.mcp-claude-say/\n├── .env                   # TTS configuration (TTS_BACKEND, GOOGLE_CLOUD_API_KEY, etc.)\n├── mcp_server.py          # TTS server\n├── listen/                # STT module\n│   ├── mcp_server.py      # STT server\n│   ├── parakeet_transcriber.py\n│   └── ptt_controller.py\n├── shared/                # Coordination\n└── venv/                  # Python environment\n\n~/.claude/skills/\n├── speak/                 # /speak skill\n│   └── SKILL.md\n└── conversation/          # /conversation skill\n    └── SKILL.md\n```\n\n## Uninstallation\n\n```bash\n./uninstall.sh\n```\n\nThe uninstaller will ask if you want to remove cached models (Parakeet MLX ~2.3GB). Choose \"Keep models\" for faster reinstallation later, or \"Remove everything\" to free up disk space.\n\n## Troubleshooting\n\n### No sound\n\n```bash\n# Test macOS speech\nsay \"Hello world\"\n```\n\n### STT not working\n\n```bash\n# Check Parakeet MLX\n~/.mcp-claude-say/venv/bin/python -c \"import parakeet_mlx; print('OK')\"\n\n# Check audio capture\n~/.mcp-claude-say/venv/bin/python -c \"import sounddevice; print(sounddevice.query_devices())\"\n```\n\n### PTT key not detected (especially in VSCode)\n\nThe PTT hotkey uses `pynput` which requires **Accessibility permissions** on macOS. Without these permissions, the keyboard listener starts successfully but never receives key events.\n\n**To fix:**\n\n1. Open **System Settings** → **Privacy \u0026 Security** → **Accessibility**\n2. Click the **+** button (unlock with your password if needed)\n3. Add your terminal application:\n   - For VSCode: `/Applications/Visual Studio Code.app`\n   - For Cursor: `/Applications/Cursor.app`\n   - For Terminal: `/Applications/Utilities/Terminal.app`\n   - For iTerm2: `/Applications/iTerm.app`\n4. **Enable the checkbox** next to the app\n5. **Restart the application completely** (quit and reopen)\n\n**Still not working?**\n\n- Try a different hotkey: `start_ptt_mode(\"f13\")` or `start_ptt_mode(\"alt_r\")`\n- Check logs: `tail -f /tmp/claude-listen.log`\n- Verify pynput works: Run a simple pynput test script outside of Claude Code\n\n**Note:** Some keys may work without Accessibility permissions (like function keys F13-F15), but modifier keys (Cmd, Alt, Ctrl) always require permissions.\n\n## Performance\n\n| Metric | Value |\n|--------|-------|\n| STT Speed | ~60x real-time (Parakeet MLX) |\n| STT RAM | ~2 GB |\n| TTS Latency | \u003c 100ms |\n\n\u003e **Note:** The first transcription is slow (~10-15 seconds) as the Parakeet MLX model loads into memory. Subsequent transcriptions are near-instant.\n\n## Tested Environments\n\n| Environment | Status | Notes |\n|-------------|--------|-------|\n| **Terminal** (macOS native) | ✅ Works | |\n| **iTerm2** | ✅ Works | |\n| **Cursor** | ⚠️ Should work | Not yet tested |\n| **VSCode Terminal** + Claude Code CLI | ✅ Works | |\n| **VSCode** + Claude Code GUI extension | ❌ Not working | Conversation mode not stable |\n\n\u003e **Help wanted!** If you test mcp-claude-say in other environments, please [open an issue](https://github.com/alamparelli/mcp-claude-say/issues) to report your results.\n\n## Changelog\n\n### v0.3.0 - Voice Conversation Mode (Jan 2026)\n\n**Kokoro TTS Backend** (PR #9)\n- New `kokoro` TTS backend using MLX-Audio with 54 voices across 9 languages\n- Supports English, Spanish, French, Italian, Portuguese, Japanese, Chinese, Hindi\n- Configure with `TTS_BACKEND=kokoro` and `KOKORO_VOICE=af_heart`\n\n**Seamless Conversation Flow**\n- **VAD auto-stop**: Recording stops automatically when you finish speaking\n- **Auto-start**: Recording restarts automatically after Claude responds\n- **Barge-in**: Press PTT to interrupt Claude mid-sentence\n- Press PTT once to start, then conversation flows naturally\n\n### v0.2.0 - TTS Configuration (Jan 2026)\n\n**Installer Improvements** (PR #7)\n- Interactive TTS backend selection (macOS, Google Cloud, Kokoro)\n- Google Cloud TTS setup wizard with API key and voice selection\n- Centralized configuration via `~/.mcp-claude-say/.env`\n- Model cache cleanup option during uninstall\n\n## License\n\nMIT\n\n---\n\n**Enjoy your voice-enabled AI assistant!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falamparelli%2Fmcp-claude-say","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falamparelli%2Fmcp-claude-say","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falamparelli%2Fmcp-claude-say/lists"}