语音MCP服务器
一个基于Bun、React和ElevenLabs构建的语音启用型MCP（模型上下文协议）服务器。该服务器为大型语言模型（LLM）提供了三种工具，以实现语音交互： speak， listen，以及 action。
特点/特性
- 🎤 语音转文字以下是原文内容的翻译：带三种模式的Web语音API：
- 手册点击开始录音，点击发送按钮 - PTT（Push-to-Talk）翻译为中文是“按讲”或“一键通”说话时按住按钮，松开发送 - 汽车在1.5秒的静音后自动发送
- 🔊 文本转语音ElevenLabs 流媒体音频
- 💬 聊天界面Facebook Messenger风格的用户界面
- 📊 行动追踪附在大型语言模型（LLM）响应上的可折叠操作日志
- 🔌 WebSocket（网络套接字协议）实时音频流和状态更新
- ⚡ MCP 工具通过stdio传输暴露的三个工具
先决条件
- 面包卷 版本1.0.0或更高版本
- ElevenLabs API密钥
- 推荐使用支持Web Speech API的现代浏览器（Chrome、Edge浏览器）
使用 npx 快速入门
使用这个MCP服务器的最简单方法是通过npx：
# Install globally
npm install -g voice-mcp
# Or run directly with npx
npx voice-mcp然后在您的MCP客户端（如Claude Desktop、Claude Code等）中进行配置：
{
"mcpServers": {
"voice-mcp": {
"command": "npx",
"args": ["voice-mcp"],
"env": {
"ELEVENLABS_API_KEY": "your_api_key_here",
"MCP_HTTP_PORT": "53245"
}
}
}
}打开你的浏览器以访问 http://localhost:53245 访问语音界面！
从源代码安装
# Clone the repository
git clone https://github.com/codingbutter/simple-voice-mcp.git
cd simple-voice-mcp
# Install dependencies
bun install
# Copy environment example
cp .env.example .env
# Edit .env and add your ElevenLabs API key
# ELEVENLABS_API_KEY=your_api_key_here发展
启动开发服务器（HTTP/WebSocket + MCP 标准控制台）：
# Set your API key
export ELEVENLABS_API_KEY="your_api_key_here"
# Run in development mode with HMR
bun dev服务器将：
- 在端口3000上启动一个HTTP服务器（可通过
MCP_HTTP_PORT) - 在（指定地址）上提供React UI服务
http://localhost:3000 - 通过标准输入输出监听MCP请求
生产
# Build the frontend
bun run build
# Run in production mode
NODE_ENV=production ELEVENLABS_API_KEY="your_key" bun startMCP配置
克劳德代码（自动）
这个项目包括一个 .mcp.json 文件，用于自动配置服务器并应用Claude代码：
- 添加您的ElevenLabs API密钥 to
.mcp.json：
{
"env": {
"ELEVENLABS_API_KEY": "your_api_key_here"
}
}- 重启Claude代码 - 服务器将自动启动
- 打开浏览器 to
http://localhost:53245
服务器已配置为 autoStart: true因此，当Claude Code启动时，它会自动开始运行。
Claude Desktop 或其他 MCP 客户端
要将此用作与Claude Desktop或其他MCP客户端配合的MCP服务器，请在您的MCP配置中添加以下内容：
{
"mcpServers": {
"voice-mcp": {
"command": "bun",
"args": ["run", "/absolute/path/to/simple-voice-mcp/src/index.tsx"],
"env": {
"ELEVENLABS_API_KEY": "your_api_key_here",
"MCP_HTTP_PORT": "53245",
"ELEVEN_VOICE_ID": "21m00Tcm4TlvDq8ikWAM",
"ELEVEN_MODEL_ID": "eleven_flash_v2_5"
}
}
}
}MCP 工具
服务器提供了三种工具：
speak(text, listen?, timeout_ms?, voiceId?, modelId?)
为连接的客户端生成并流式传输文本转语音音频。
参数：
text（字符串，必填）：要转换为语音的文本listen(布尔值，可选)：如果为真，在说完后等待用户响应timeout_ms（数字，可选）：当 listen=true 时的超时时间（默认：60000 毫秒）voiceId（字符串，可选）：ElevenLabs 语音ID（默认：Rachel）modelId（字符串，可选）：ElevenLabs 模型 ID（默认：eleven_flash_v2_5）
返回值：
{ ok: true, message, messages? }- 如果 listen=true，则包含用户的消息
listen(timeout_ms?)
等待客户端的文本输入（阻塞，直到用户发送文本或超时）。
参数：
timeout_ms(数字，可选)：超时时间（毫秒）（默认：60000）
返回值：
{ messages: string[] }- 消息数组（超时时为空）
action(text)
向客户端用户界面发送状态或操作更新。显示为可折叠部分。
参数：
text(字符串，必填)：要显示的操作/状态文本（例如，“正在读取文件X”，“正在运行测试”）
返回值：
{ ok: true }
注： 只发送正在执行的具体操作，不要发送评论或解释。
使用MCP Inspector进行测试
# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector
# Test the server
export ELEVENLABS_API_KEY="your_key"
npx @modelcontextprotocol/inspector bun src/index.tsx建筑
┌─────────────────────────────────────────┐
│ MCP Client (Claude Desktop, etc.) │
└───────────────┬─────────────────────────┘
│ stdio (JSON-RPC)
│
┌───────────────▼─────────────────────────┐
│ MCP Server (Bun Process) │
│ ├─ stdio transport │
│ ├─ Three tools: speak/listen/action │
│ └─ HTTP/WebSocket server │
└───────────────┬─────────────────────────┘
│ HTTP + WebSocket
│
┌───────────────▼─────────────────────────┐
│ Browser UI (React) │
│ ├─ Chat interface │
│ ├─ Web Speech API (STT) │
│ ├─ Audio playback (TTS) │
│ └─ WebSocket client │
└─────────────────────────────────────────┘环境变量
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
ELEVENLABS_API_KEY 您的ElevenLabs API密钥 | |||
MCP_HTTP_PORT | ❌ | 3000 | HTTP/WS 服务器端口 |
ELEVEN_VOICE_ID | ❌ | Rachel音色 | 默认音色ID |
ELEVEN_MODEL_ID | ❌ | eleven_flash_v2_5 | 默认模型 |
NODE_ENV | ❌ | development | 环境模式 |
项目结构
src/
├── index.tsx # Main entry point (MCP + HTTP server)
├── App.tsx # React root component
├── frontend.tsx # React DOM setup
├── mcp/
│ └── tools.ts # MCP tool implementations
├── server/
│ ├── http.ts # HTTP + WebSocket server
│ ├── websocket.ts # WebSocket manager
│ └── tts.ts # ElevenLabs TTS manager
├── hooks/
│ ├── useWebSocket.ts # WebSocket client hook
│ └── useSpeechRecognition.ts # Web Speech API hook
└── components/
├── chat/
│ ├── ChatInterface.tsx # Main chat UI
│ └── ChatMessage.tsx # Message bubble component
└── ui/ # shadcn/ui components重要注意事项
- stdio 约束服务器使用 stdout 进行 MCP JSON-RPC。所有日志记录均输出到 stderr。
- 浏览器兼容性网络语音API在Chrome/Edge浏览器中表现最佳
- 多实例每个MCP服务器实例都需要一个唯一的端口（通过设置
MCP_HTTP_PORT）
文档
见 项目范围说明文档（Project_Scope.md） 以获取详细的技术规格。 见 QUICKSTART.md 翻译为中文是：“快速入门指南.md” 以下是快速设置指南。
许可证
麻省理工学院 - 看 许可证 详情请见。
使用了（或构建于）
- 面包 - 运行时 & 打包工具
- React 19 - 用户界面（UI）框架
- Tailwind CSS v4 - 搭配/造型
- shadcn/ui（可译为“Shadcn的用户界面组件库”或根据具体上下文简化为“Shadcn UI”，但直接保留原样也是可接受的，因为这是一个专有名词或项目名） - 用户界面组件
- ElevenLabs（可译为“十一实验室”或根据具体语境保留原名） - 文本转语音
- 模型上下文协议 - MCP SDK（多客户端协议软件开发工具包）