MCP Voice Assistant
一种支持语音的人工智能个人助理，利用模型上下文协议（MCP）通过自然语音交互集成多种工具和服务。
特性
- 🎤 语音输入：使用OpenAI Whisper实时语音转文本
- 🔊 语音输出：使用ElevenLabs的高质量文本转语音（带pyttsx3回退）
- 🤖 AI驱动：具有记忆持久性的对话式人工智能
- 🌐 多个模型提供者：可与任何支持工具调用的LLM提供者（OpenAI、Anthropic、Groq、LLama等）配合使用
- 🛠️ 多工具集成：无缝连接到任何MCP服务器：
- 💾 会话记忆：在交互中保持上下文
- 🎯 可扩展：易于添加新的MCP服务器和功能
建筑
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐
│ User Voice │ --> │ Speech-to- │ --> │ LLM with │ --> │ Text-to- │
│ Input │ │ Text (STT) │ │ MCPAgent │ │ Speech (TTS) │
└─────────────┘ └──────────────┘ └─────────────┘ └──────────────┘
Whisper │ ElevenLabs
│
┌──────▼──────┐
│ MCP Servers │
├─────────────┤
│ • Linear │
│ • Playwright│
│ • Filesystem│
└─────────────┘安装
先决条件
- Python 3.11+
- 紫外线 （Python包管理器）：
pip install uv或pipx install uv - Node.js （适用于MCP服务器）
- 系统相关性:
- macOS： brew install portaudio - Ubuntu/Debian： sudo apt-get install portaudio19-dev - Windows:PyAudio控制盘包括PortAudio
从源代码安装
# 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 .配置
环境变量
创建一个 .env 项目根目录中的文件（请参见 .env.example 完整模板）：
# 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使用CLI时，可以通过命令行参数覆盖所有环境变量。
MCP服务器配置
助手从以下位置加载MCP服务器配置 mcp_servers.json 在项目根中。默认情况下，它包括：
- 剧作家：Web自动化和浏览器控制
- 线性：任务和项目管理
要添加更多服务器，请编辑 mcp_servers.json 或复制 mcp_servers.example.json 其中包括额外的服务器，如：
- 文件系统、github、gitlab、谷歌驱动器、postgres、sqlite、slack、内存、木偶师、勇敢搜索、获取
配置中的环境变量（如 ${GITHUB_PERSONAL_ACCESS_TOKEN})将自动从您的 .env 文件。
要以编程方式覆盖默认配置，请执行以下操作：
config = {
"mcpServers": {
"your_server": {
"command": "npx",
"args": ["-y", "@your-org/mcp-server"],
"env": {"YOUR_API_KEY": "${YOUR_API_KEY}"}
}
}
}运行助手
安装后，运行助手：
# 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备注：命令行参数优先于环境变量。
更改模型提供程序
语音助手通过LangChain支持多个LLM提供商。任何具有工具调用功能的模型都可以使用：
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"
)备注：只能使用具有工具调用功能的模型。请查看您的模型提供商的文档，了解支持的模型。
更改语音设置
初始化时传递不同的参数：
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
)故障排除
常见问题
- 未检测到音频输入
- 检查麦克风权限 - 降低 silence_threshold 价值 - 验证PyAudio： python -c "import pyaudio; pyaudio.PyAudio()"
- TTS不工作
- 验证API密钥设置是否正确 - 检查API配额 - 如果ElevenLabs发生故障，系统将回退到pyttsx3
- MCP服务器连接问题
- 确保已安装Node.js - 检查npx下载的互联网连接 - 验证特定服务器的API密钥
- 高延迟
- 使用更快的LLM模型（例如。， gpt-3.5-turbo) - 减少 max_steps MCPAgent - 考虑使用本地模型
贡献
我们欢迎捐款！请查看我们的 贡献指南 了解详情。
- 分叉存储库
- 创建功能分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求