{"id":29360069,"url":"https://github.com/batchlion/mcp-audio-server","last_synced_at":"2026-04-11T21:08:24.659Z","repository":{"id":303071485,"uuid":"1014311992","full_name":"BatchLion/mcp-audio-server","owner":"BatchLion","description":"A powerful Model Context Protocol (MCP) server that provides text-to-speech and audio playback capabilities for Claude Desktop and other MCP clients.","archived":false,"fork":false,"pushed_at":"2025-07-05T13:39:25.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-05T14:40:01.301Z","etag":null,"topics":["ai-tools","audio","audio-server","claude-desktop","mcp","model-context-protocol","python","speech-synthesis","text-to-speech","tts"],"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/BatchLion.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}},"created_at":"2025-07-05T13:19:06.000Z","updated_at":"2025-07-05T13:39:28.000Z","dependencies_parsed_at":"2025-07-05T14:52:43.853Z","dependency_job_id":null,"html_url":"https://github.com/BatchLion/mcp-audio-server","commit_stats":null,"previous_names":["batchlion/mcp-audio-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/BatchLion/mcp-audio-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BatchLion%2Fmcp-audio-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BatchLion%2Fmcp-audio-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BatchLion%2Fmcp-audio-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BatchLion%2Fmcp-audio-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BatchLion","download_url":"https://codeload.github.com/BatchLion/mcp-audio-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BatchLion%2Fmcp-audio-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264411163,"owners_count":23603804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["ai-tools","audio","audio-server","claude-desktop","mcp","model-context-protocol","python","speech-synthesis","text-to-speech","tts"],"created_at":"2025-07-09T07:09:43.966Z","updated_at":"2025-11-05T23:04:05.594Z","avatar_url":"https://github.com/BatchLion.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Audio Server 🔊\n\n*[English](README.md) | [中文](README_CN.md)*\n\nA powerful Model Context Protocol (MCP) server that provides text-to-speech and audio playback capabilities for Claude Desktop and other MCP clients.\n\n## ✨ Features\n\n- **🗣️ High-Quality TTS**: \n  - **Smart Language Detection**: Automatically uses Google's TTS for high-quality Chinese speech and falls back to the system's TTS for other languages.\n  - **Voice Selection**: For non-Chinese text, list and select from various system-installed voices.\n  - **Customizable Speech**: Adjust rate and volume for a tailored listening experience.\n- **🎵 Audio File Playback**: Play various audio formats (WAV, MP3, OGG, etc.).\n- **⏹️ Audio Control**: Stop playback and get real-time audio status.\n- **🔌 MCP Compliant**: Fully compatible with Claude Desktop and MCP specification 2024-11-05.\n- **🛡️ Error Handling**: Robust error handling and validation.\n- **📊 Status Monitoring**: Real-time audio system status and playback information.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.8+\n- Claude Desktop (for MCP integration)\n- System audio capabilities\n\n### Installation\n\n1. **Clone the repository:**\n```bash\ngit clone https://github.com/yourusername/mcp-audio-server.git\ncd mcp-audio-server\n```\n\n2. **Install dependencies:**\n```bash\npip install -r requirements.txt\n```\n\n3. **Configure Claude Desktop:**\nAdd to your `claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"audio-server\": {\n      \"command\": \"/path/to/your/python\",\n      \"args\": [\"/path/to/mcp-audio-server/audio_server.py\"]\n    }\n  }\n}\n```\n\n4. **Restart Claude Desktop** and start using audio features!\n\n## 🛠️ Available Tools\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `speak_text` | Convert text to speech. Automatically uses Google TTS for Chinese. | `text` (required), `rate` (optional), `volume` (optional), `voice_id` (optional, for non-Chinese) |\n| `list_voices` | List available TTS voices for non-Chinese languages. | None |\n| `play_audio_file` | Play an audio file. | `file_path` (required), `volume` (optional) |\n| `stop_audio` | Stop current audio playback. | None |\n| `get_audio_status` | Get audio system status. | None |\n\n## 📖 Usage Examples\n\n### Text-to-Speech (Chinese)\n```\n\"请用语音说出 '你好，世界'\"\n```\n*This will automatically use Google TTS for a natural-sounding voice.*\n\n### Text-to-Speech (English, with a specific voice)\n1.  **First, list available voices:**\n    ```\n    \"List all available voices\"\n    ```\n2.  **Then, use a specific voice ID from the list:**\n    ```\n    \"Use the voice with ID 'com.apple.speech.synthesis.voice.daniel' to say 'Hello, this is a test.'\"\n    ```\n\n### Play Audio File\n```\n\"Play the audio file at /path/to/music.mp3\"\n```\n\n### Stop Audio\n```\n\"Stop the current audio playback\"\n```\n\n### Check Status\n```\n\"What's the current audio status?\"\n```\n\n## 🧪 Testing\n\nRun the comprehensive test suite:\n```bash\n# Test all MCP methods\npython test_all_mcp_methods.py\n\n# Test Claude Desktop format compatibility\npython test_claude_desktop_format.py\n\n# Test audio functionality\npython test_audio_server.py\n\n# Interactive testing mode\npython audio_server.py --interactive\n```\n\n## 📁 Project Structure\n\n```\nmcp-audio-server/\n├── audio_server.py              # Main MCP server\n├── requirements.txt             # Python dependencies\n├── README.md                   # English documentation (default)\n├── README_CN.md                # Chinese documentation\n├── .gitignore                  # Git ignore rules\n├── tests/                      # Test files\n│   ├── test_*.py               # Various tests\n│   └── validate_*.py           # Validation scripts\n├── examples/                   # Configuration examples\n│   ├── claude_desktop_config.json\n│   └── other config files\n├── scripts/                    # Utility scripts\n│   ├── install_and_setup.sh\n│   └── other shell scripts\n└── docs/                       # Additional documentation\n    ├── INTEGRATION_GUIDE.md    # Integration guide\n    ├── USAGE_GUIDE.md          # Usage guide\n    └── FINAL_INTEGRATION_REPORT.md\n```\n\n## 🔧 Configuration\n\n### Claude Desktop Configuration\n\nThe server integrates seamlessly with Claude Desktop. Make sure your configuration file is properly set up:\n\n**Location:** \n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n**Example configuration:**\n```json\n{\n  \"mcpServers\": {\n    \"audio-server\": {\n      \"command\": \"/Users/yourusername/miniconda3/envs/mcp_agent/bin/python\",\n      \"args\": [\"/path/to/mcp-audio-server/audio_server.py\"]\n    }\n  }\n}\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **Audio not playing**: Check system audio settings and permissions\n2. **TTS not working**: Ensure pyttsx3 is properly installed\n3. **MCP connection issues**: Verify Claude Desktop configuration path\n4. **Permission errors**: Check file permissions for audio files\n\n### Debug Mode\n\nRun in interactive mode for debugging:\n```bash\npython audio_server.py --interactive\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 🙏 Acknowledgments\n\n- Built with the Model Context Protocol (MCP)\n- Uses pyttsx3 for text-to-speech\n- Uses pygame for audio playback\n- Compatible with Claude Desktop\n\n## 📞 Support\n\nIf you encounter any issues or have questions:\n1. Check the troubleshooting section\n2. Review the integration guide\n3. Open an issue on GitHub\n4. Check Claude Desktop documentation\n\n---\n\n**Made with ❤️ for the MCP community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbatchlion%2Fmcp-audio-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbatchlion%2Fmcp-audio-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbatchlion%2Fmcp-audio-server/lists"}