Simple Voice MCP

语音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 start

MCP配置

克劳德代码（自动）

这个项目包括一个 .mcp.json 文件，用于自动配置服务器并应用Claude代码：

1. 添加您的ElevenLabs API密钥 to .mcp.json：

   {
     "env": {
       "ELEVENLABS_API_KEY": "your_api_key_here"
     }
   }

1. 重启Claude代码 - 服务器将自动启动

1. 打开浏览器 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                    │
└─────────────────────────────────────────┘

环境变量

项目结构

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（多客户端协议软件开发工具包）