MCP Voice Assistant

Un asistente personal de IA activado por voz que integra múltiples herramientas y servicios a través de interacciones de voz naturales usando MCP.

GitHub
34
Prueba este MCPPatrocinado

Documentación

MCP Voice Assistant

construido con

mcp use logo

Un asistente personal de IA con voz que aprovecha el Model Context Protocol (MCP) para integrar múltiples herramientas y servicios mediante interacciones de voz naturales.

Características

  • 🎤 Entrada de voz: Transcripción de voz en tiempo real usando OpenAI Whisper
  • 🔊 Salida de voz: Texto a voz de alta calidad usando ElevenLabs (con respaldo de pyttsx3)
  • 🤖 Impulsado por IA: IA conversacional con persistencia de memoria
  • 🌐 Múltiples proveedores de modelos: Funciona con cualquier proveedor de LLM que admita llamadas a herramientas (OpenAI, Anthropic, Groq, LLama, etc.)
  • 🛠️ Integración multiherramienta: Se conecta sin problemas a cualquier servidor MCP:
  • 💾 Memoria conversacional: Mantiene el contexto entre interacciones
  • 🎯 Extensible: Fácil de añadir nuevos servidores MCP y capacidades

Arquitectura

┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌──────────────┐
│ User Voice  │ --> │ Speech-to-   │ --> │  LLM with   │ --> │ Text-to-     │
│   Input     │     │ Text (STT)   │     │  MCPAgent   │     │ Speech (TTS) │
└─────────────┘     └──────────────┘     └─────────────┘     └──────────────┘
                         Whisper                 │                ElevenLabs
                                                 │
                                          ┌──────▼──────┐
                                          │ MCP Servers │
                                          ├─────────────┤
                                          │ • Linear    │
                                          │ • Playwright│
                                          │ • Filesystem│
                                          └─────────────┘

Instalación

Requisitos previos

  1. Python 3.11+
  2. uv (administrador de paquetes de Python): pip install uv o pipx install uv
  3. Node.js (para servidores MCP)
  4. Dependencias del sistema:
    • macOS: brew install portaudio
    • Ubuntu/Debian: sudo apt-get install portaudio19-dev
    • Windows: la rueda de PyAudio incluye PortAudio

Instalar desde el código fuente

# Clone the repository
git clone https://github.com/yourusername/mcp-voice-assistant.git
cd mcp-voice-assistant

# Create a virtual environment with uv
uv venv

# Activate the virtual environment
# On Linux/macOS:
source .venv/bin/activate
# On Windows:
# .venv\Scripts\activate

# Install in development mode
uv pip install -e .

# Or install directly
uv pip install .

Configuración

Variables de entorno

Cree un archivo .env en la raíz de su proyecto (consulte .env.example para una plantilla completa):

# Required
OPENAI_API_KEY=your-openai-api-key

# Optional but recommended for better voice output
ELEVENLABS_API_KEY=your-elevenlabs-api-key

# Optional - Model Provider Settings
# You can use any model provider that supports tool calling
OPENAI_API_KEY=your-openai-api-key              # For OpenAI models
ANTHROPIC_API_KEY=your-anthropic-api-key        # For Claude models
GROQ_API_KEY=your-groq-api-key                  # For Groq models

# Model selection (defaults to gpt-4)
OPENAI_MODEL=gpt-4                              # OpenAI: gpt-4, gpt-4-turbo, gpt-3.5-turbo
# Or use other providers:
# ANTHROPIC_MODEL=claude-3-5-sonnet-20240620   # Anthropic Claude
# GROQ_MODEL=llama3-8b-8192                    # Groq LLama

# Voice Settings
ELEVENLABS_VOICE_ID=ZF6FPAbjXT4488VcRRnw      # Default: Rachel voice

# Optional - Audio Configuration
VOICE_SILENCE_THRESHOLD=500                     # Lower = more sensitive
VOICE_SILENCE_DURATION=1.5                      # Seconds to wait after speech

# Optional - Assistant Configuration
ASSISTANT_SYSTEM_PROMPT="You are a helpful voice assistant..."  # Customize personality

# Optional - MCP Server Specific
LINEAR_API_KEY=your-linear-api-key              # For Linear integration

Todas las variables de entorno se pueden sobrescribir mediante argumentos de línea de comandos al usar la CLI.

Configuración del servidor MCP

El asistente carga las configuraciones de los servidores MCP desde mcp_servers.json en la raíz del proyecto. Por defecto, incluye:

  • playwright: Automatización web y control del navegador
  • linear: Gestión de tareas y proyectos

Para añadir más servidores, edite mcp_servers.json o copie mcp_servers.example.json que incluye servidores adicionales como:

  • filesystem, github, gitlab, google-drive, postgres, sqlite, slack, memory, puppeteer, brave-search, fetch

Las variables de entorno en la configuración (como ${GITHUB_PERSONAL_ACCESS_TOKEN}) se sustituyen automáticamente desde su archivo .env.

Para sobrescribir la configuración predeterminada programáticamente:

config = {
    "mcpServers": {
        "your_server": {
            "command": "npx",
            "args": ["-y", "@your-org/mcp-server"],
            "env": {"YOUR_API_KEY": "${YOUR_API_KEY}"}
        }
    }
}

Ejecutar el asistente

Después de la instalación, ejecute el asistente:

# Using uv
uv run python voice_assistant/agent.py

# Or using python directly
python voice_assistant/agent.py

# Override specific settings via command line
python voice_assistant/agent.py --model gpt-3.5-turbo --silence-threshold 300

# Provide all settings via command line (no .env needed)
python voice_assistant/agent.py \
  --openai-api-key YOUR_KEY \
  --elevenlabs-api-key YOUR_ELEVENLABS_KEY \
  --model gpt-4 \
  --voice-id ZF6FPAbjXT4488VcRRnw \
  --silence-threshold 500 \
  --silence-duration 1.5

# See all available options
python voice_assistant/agent.py --help

Nota: Los argumentos de línea de comandos tienen prioridad sobre las variables de entorno.

Cambiar el proveedor de modelos

El asistente de voz admite múltiples proveedores de LLM a través de LangChain. Se puede usar cualquier modelo con capacidades de llamada a herramientas:

from langchain_openai import ChatOpenAI
from langchain_anthropic import ChatAnthropic
from langchain_groq import ChatGroq

# Using OpenAI (default)
assistant = VoiceAssistant(
    openai_api_key="your-key",
    model="gpt-4"  # or gpt-4-turbo, gpt-3.5-turbo
)

# Using Anthropic Claude
llm = ChatAnthropic(
    api_key="your-anthropic-key",
    model="claude-3-5-sonnet-20240620"
)
assistant = VoiceAssistant(
    llm=llm,  # Pass custom LLM instance
    elevenlabs_api_key="your-key"
)

# Using Groq
llm = ChatGroq(
    api_key="your-groq-key",
    model="llama3-8b-8192"
)
assistant = VoiceAssistant(
    llm=llm,
    elevenlabs_api_key="your-key"
)

Nota: Solo se pueden usar modelos con capacidades de llamada a herramientas. Consulte la documentación de su proveedor de modelos para conocer los modelos compatibles.

Cambiar la configuración de voz

Pase diferentes parámetros al inicializar:

assistant = VoiceAssistant(
    openai_api_key="your-key",
    elevenlabs_api_key="your-key",
    elevenlabs_voice_id="different-voice-id",  # Change voice
    silence_threshold=300,  # More sensitive
    silence_duration=2.0,   # Wait longer
    model="gpt-3.5-turbo"  # Faster model
)

Solución de problemas

Problemas comunes

  1. No se detecta entrada de audio

    • Verifique los permisos del micrófono
    • Baje el valor de silence_threshold
    • Verifique PyAudio: python -c "import pyaudio; pyaudio.PyAudio()"

  2. TTS no funciona

    • Verifique que las claves de API estén configuradas correctamente
    • Compruebe las cuotas de API
    • El sistema recurrirá a pyttsx3 si ElevenLabs falla

  3. Problemas de conexión con el servidor MCP

    • Asegúrese de que Node.js esté instalado
    • Compruebe la conexión a Internet para las descargas de npx
    • Verifique las claves de API para servidores específicos

  4. Alta latencia

    • Use un modelo LLM más rápido (por ejemplo, gpt-3.5-turbo)
    • Reduzca max_steps en MCPAgent
    • Considere usar modelos locales

Contribuciones

¡Agradecemos las contribuciones! Consulte nuestras Guías de contribución para más detalles.

  1. Haga un fork del repositorio
  2. Cree su rama de características (git checkout -b feature/amazing-feature)
  3. Haga commit de sus cambios (git commit -m 'Add amazing feature')
  4. Haga push a la rama (git push origin feature/amazing-feature)
  5. Abra una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para más detalles.

Reconocimientos

Soporte