Voice Assistant
- other
About
What is Voice Assistant?
Voice Assistant is a Python-based application that integrates voice interaction (speech-to-text, text-to-speech, and voice activity detection) with a Multi-Content Processor (MCP) to enable WhatsApp messaging. It runs locally on Linux, macOS, or Windows (Python ≥3.13, using uv) and connects to LiveKit’s real-time audio platform. It is built for developers who want to create a voice‑controlled assistant that can send and receive WhatsApp messages via an MCP server.
How to use Voice Assistant?
1. Clone the repository, create a virtual environment with uv venv, and activate it.
2. Run uv sync to install dependencies.
3. Set the required environment variables (LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET, CARTESIA_API_KEY, OPENAI_API_KEY) in a .env file.
4. Configure the WhatsApp MCP server path in mcp_config.json (replace placeholders with absolute paths to uv and the whatsapp-mcp-server directory).
5. Start the assistant with uv run voice-assistant-cli.
6. Open LiveKit Agents Playground in a browser and connect to your local agent.
Key features of Voice Assistant
- Voice‑activated assistant using Silero Voice Activity Detection (VAD)
- Real‑time speech‑to‑text via OpenAI Whisper (via LiveKit)
- Text‑to‑speech using Cartesia AI
- WhatsApp message handling through a Multi‑Content Processor (MCP)
- Runs locally with Python and uv for easy dependency management
- Connects to LiveKit Agents Playground for testing and debugging
Use cases of Voice Assistant
- Build a voice‑controlled assistant that reads and sends WhatsApp messages hands‑free
- Prototype a multi‑modal agent that combines voice input with external service integration
- Create a personal assistant that responds to spoken queries and acts on WhatsApp contacts or groups
FAQ from Voice Assistant
What prerequisites are needed?
Python ≥3.13 and uv (Python packager and virtual environment manager) must be installed on your system. You also need accounts/API keys for LiveKit, Cartesia, and OpenAI.
How do I configure the WhatsApp MCP?
Edit the mcp_config.json file with the absolute path to your uv binary and the full path to the whatsapp-mcp-server directory. The server must be running separately and configured according to its own documentation.
How do I run the assistant?
After completing the setup steps, run uv run voice-assistant-cli from the project root. The assistant will start and connect to LiveKit; you can then interact with it via the LiveKit Agents Playground.
What services are used for speech and AI?
Silero for voice activity detection, OpenAI for speech‑to‑text and language model responses, and Cartesia for text‑to‑speech. Real‑time audio handling is managed by LiveKit.
Is there any built‑in model download required?
No manual download is needed inside the script. The LiveKit plugins (including Silero) handle their own model setup when the assistant starts.
Details
- Author
- autometa-dev
- GitHub stars
- 18
- Category
- other
- Repository
- autometa-dev/whatsapp-mcp-voice-agent
Voice Assistant
A simple voice assistant using LiveKit, Cartesia, OpenAI, Silero, and a Multi-Content Processor (MCP) for WhatsApp integration.
Prerequisites
- Python >=3.13
- uv (Python packager and virtual environment manager)
Setup
1. Clone the repository:
git clone <your-repo-url>
cd voice-assistant
2. Create and activate a virtual environment (using uv):
uv venv
source .venv/bin/activate # On Linux/macOS
# .\.venv\Scripts\activate # On Windows
3. Install dependencies:
uv sync
4. Set up Environment Variables:
Create a file named .env in the root of the project and add the following environment variables with your actual values.
You can copy the example below:
LIVEKIT_URL=
LIVEKIT_API_KEY=
LIVEKIT_API_SECRET=
CARTESIA_API_KEY=
OPENAI_API_KEY=
- LIVEKIT_URL: Your LiveKit server URL.
- LIVEKIT_API_KEY: Your LiveKit API key.
- LIVEKIT_API_SECRET: Your LiveKit API secret.
- CARTESIA_API_KEY: Your Cartesia API key for Text-to-Speech.
- OPENAI_API_KEY: Your OpenAI API key for Speech-to-Text and LLM operations.
5. Configure WhatsApp MCP (Multi-Content Processor):
This project uses an MCP to interact with WhatsApp. You need to have your WhatsApp MCP server running and configured.
Update the mcp_config.json file in the root of this project with the correct paths for your MCP setup:
{
"mcpServers": {
"whatsapp": {
"command": "{{PATH_TO_UV}}",
"args": [
"--directory",
"{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
]
}
}
}
- Replace {{PATH_TO_UV}} with the absolute path to your uv executable. You can find this by running which uv (on Linux/macOS) or where uv (on Windows) in your terminal.
- Replace {{PATH_TO_SRC}} with the absolute path to the directory containing your whatsapp-mcp project. For example, if your whatsapp-mcp project is in /Users/me/dev/whatsapp-mcp, then this value should be /Users/me/dev. The final path in the config will be /Users/me/dev/whatsapp-mcp/whatsapp-mcp-server.
Running the Assistant
1. (Optional) Download necessary model files (e.g., for Silero VAD):
The voice.py script might have a command or automatically download necessary models on first run. The example below shows a hypothetical command if your voice.py supported it.
# If your voice.py has a download command, e.g.:
# uv run python voice.py download-files
Currently, the
voice.py script uses livekit.agents.cli.run_app, which typically handles its own setup for plugins like Silero.
2. Start the voice assistant:
uv run voice-assistant-cli
This uses the
voice-assistant-cli script defined in pyproject.toml.
Connecting to the Playground
Once the assistant is running, you can load the LiveKit Agents Playground in your browser and connect to your local agent.
---
Note: This README assumes you have uv installed and configured in your system PATH."# Whatsapp-mcp-voice-agent"
