MCP Voice Assistant

Um assistente pessoal de IA habilitado por voz que integra múltiplas ferramentas e serviços por meio de interações naturais de voz usando MCP.

GitHub

Documentação

Assistente de Voz MCP

construído com

Um assistente pessoal de IA habilitado por voz que utiliza o Protocolo de Contexto do Modelo (MCP) para integrar múltiplas ferramentas e serviços por meio de interações naturais por voz.

Recursos

🎤 Entrada de Voz: Transcrição de fala em tempo real usando OpenAI Whisper
🔊 Saída de Voz: Síntese de fala de alta qualidade usando ElevenLabs (com fallback para pyttsx3)
🤖 Alimentado por IA: IA conversacional com persistência de memória
🌐 Múltiplos Provedores de Modelo: Funciona com qualquer provedor de LLM que suporte chamadas de ferramenta (OpenAI, Anthropic, Groq, LLama, etc.)
🛠️ Integração Multi-Ferramenta: Conecta-se perfeitamente a qualquer servidor MCP:
💾 Memória Conversacional: Mantém contexto entre interações
🎯 Extensível: Fácil adicionar novos servidores MCP e capacidades

Arquitetura

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

Instalação

Pré-requisitos

Python 3.11+
uv (gerenciador de pacotes Python): pip install uv ou pipx install uv
Node.js (para servidores MCP)
Dependências do sistema:
- macOS: brew install portaudio
- Ubuntu/Debian: sudo apt-get install portaudio19-dev
- Windows: a wheel do PyAudio inclui PortAudio

Instale a partir do código-fonte

# 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 .

Configuração

Variáveis de ambiente

Crie um arquivo .env na raiz do seu projeto (veja .env.example para um modelo completo):

# 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 as variáveis de ambiente podem ser sobrescritas por argumentos de linha de comando ao usar a CLI.

Configuração do servidor MCP

O assistente carrega as configurações dos servidores MCP a partir de mcp_servers.json na raiz do projeto. Por padrão, inclui:

playwright: Automação web e controle de navegador
linear: Gerenciamento de tarefas e projetos

Para adicionar mais servidores, edite mcp_servers.json ou copie mcp_servers.example.json, que inclui servidores adicionais como:

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

As variáveis de ambiente na configuração (como ${GITHUB_PERSONAL_ACCESS_TOKEN}) são automaticamente substituídas a partir do seu arquivo .env.

Para sobrescrever a configuração padrão programaticamente:

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

Executando o assistente

Após a instalação, execute o assistente:

# 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: Os argumentos de linha de comando têm precedência sobre as variáveis de ambiente.

Alterando o provedor de modelo

O assistente de voz suporta múltiplos provedores de LLM através do LangChain. Qualquer modelo com capacidade de chamada de ferramenta pode ser usado:

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: Apenas modelos com capacidade de chamada de ferramenta podem ser usados. Verifique a documentação do seu provedor de modelo para saber quais modelos são suportados.

Alterando as configurações de voz

Passe parâmetros diferentes ao 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
)

Solução de problemas

Problemas comuns

Nenhuma entrada de áudio detectada
- Verifique as permissões do microfone
- Reduza o valor de silence_threshold
- Verifique o PyAudio: python -c "import pyaudio; pyaudio.PyAudio()"
TTS não está funcionando
- Verifique se as chaves de API estão configuradas corretamente
- Verifique as cotas da API
- O sistema fará fallback para pyttsx3 se ElevenLabs falhar
Problemas de conexão com o servidor MCP
- Certifique-se de que o Node.js está instalado
- Verifique a conexão com a internet para downloads via npx
- Verifique as chaves de API para servidores específicos
Alta latência
- Use um modelo LLM mais rápido (por exemplo, gpt-3.5-turbo)
- Reduza max_steps no MCPAgent
- Considere usar modelos locais

Contribuindo

Agradecemos contribuições! Consulte nossas Diretrizes de Contribuição para mais detalhes.

Faça um fork do repositório
Crie sua branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para a branch (git push origin feature/amazing-feature)
Abra um Pull Request

Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para mais detalhes.

Agradecimentos

Construído sobre mcp-use
Usa OpenAI Whisper para reconhecimento de fala
Síntese de voz alimentada por ElevenLabs
Servidores MCP do ecossistema Model Context Protocol

Suporte

📧 Email: your.email@example.com
💬 Discord: Junte-se ao nosso servidor
🐛 Issues: Issues no GitHub
📖 Documentação: Documentação completa