MCP Hands Free

MCP免提-语音输入MCP服务器

 ](https://badge.fury.io/py/mcp-hands-free)   

“你能说话的时候为什么打字？” -每个开发人员在编码时都在吃披萨

Demo *语音输入-免提与您的AI助手对话*

为什么存在

曾经尝试过：

• 🍕 在吃午饭的时候问你的人工智能助手一个问题？（油腻的键盘不好玩）
• 🏃 在跑步机上调试代码？（打字+跑步=脚踝骨折）
• 🧘 因为手腕受伤而练习“免提工作日”？（RSI是真实的，伙计们）
• 🛋️ 在房间的另一边随便和你的人工智能聊天？（懒惰达到顶峰）
• 👶 抱着婴儿编码？（多任务处理级别：父级-是的，这个仓库作者这样做，不丢人）

此MCP服务器允许您与任何兼容MCP的AI通信，而无需键入。 不再进行键盘体操。只需说出你的想法，你的AI助手就会倾听。

非常适合你的手忙碌、疲惫、肮脏或只是。…在别的地方。

______________________________________________________________________

使用Whisper语音转文本功能，为MCP兼容的AI助手（Claude Code CLI、Gemini、Qwen等）提供通用免提语音输入。

截图

浏览器界面

Browser Voice Input Interface *简洁、简洁的浏览器界面，用于录音*

终端集成

CLI Integration *与MCP兼容的AI代理无缝集成*

建筑

MCP Client (Claude, Gemini, Qwen, etc.)
  ↓ calls get_voice_input() MCP tool
MCP Server (stdio)
  ↓ HTTP POST /api/request-voice
FastAPI Server (coordination)
  ↓ stores request_id
Browser Interface
  ↓ polls /api/pending-requests
  ↓ auto-starts recording
  ↓ user speaks
  ↓ POST audio to /api/submit-voice/{request_id}
FastAPI Server
  ↓ transcribes with Whisper via Wyoming protocol
MCP Server
  ↓ polls /api/result/{request_id}
  ↓ returns transcript
MCP Client
  └─ receives transcript as user input

Architecture Diagram *数据流的可视化表示*

特性

• 免提输入 -说出你的要求，而不是打字
• 多语言支持 -法语、英语、西班牙语、德语、意大利语
• 基于浏览器的录制 -无需安装客户端软件
• 耳语STT -通过怀俄明州协议进行高质量语音识别
• 通用MCP集成 -适用于任何兼容MCP的AI客户端
• 自动录制 -当您的AI请求语音输入时，浏览器会自动开始录制

先决条件

• FastAPI服务器 -与Whisper集成的协调服务器
• 耳语服务 -兼容怀俄明州的Whisper STT服务（端口10300）
• 浏览器 -任何可通过麦克风访问的现代浏览器
• MCP客户端 -任何兼容MCP的AI代理CLI（Claude Code、Gemini、Qwen等）

安装

1.安装MCP服务器

添加到您的 .mcp.json:

{
  "mcpServers": {
    "voice-input": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "/path/to/mcp-hands-free/mcp-server",
        "claude-voice-mcp"
      ],
      "env": {
        "VOICE_SERVER_URL": "https://your-server:8766"
      }
    }
  }
}

2.启动FastAPI服务器

cd /path/to/mcp-hands-free

# Install Python dependencies
pip3 install -r requirements.txt

# Start the server (with SSL for browser microphone access)
python3 server.py

服务器在端口8766（HTTPS）上运行。

3.启动Whisper服务

# Using Wyoming-compatible Whisper service
docker run -d \
  -p 10300:10300 \
  rhasspy/wyoming-faster-whisper \
  --model base \
  --language fr

4.打开浏览器界面

导航到：

https://your-server:8766/static/voice-input.html

接受SSL证书警告（自签名）并授予麦克风权限。

用法

基本语音输入

在您的AI代理CLI中：

You: "Get my next request via voice"

你的AI呼叫 get_voice_input() 工具，浏览器自动开始录制，你说话，成绩单返回。

带语言参数

You: "Get my next request via voice in English"

工作流示例

You: Get my next request via voice
[Browser automatically starts recording]
You: [speaking] "List my vault secrets"
AI: Voice input received: "List my vault secrets"
[AI then processes your request, using other MCP tools if needed]

MCP工具API

get_voice_input

向用户请求语音输入。

参数：

• language （可选）：语言代码（fr，en，es，de，it）-默认值：“fr”
• timeout （可选）：最长等待秒数-默认值：60

退货：

• 成功： Voice input received: "transcript text"
• 超时： Voice input timed out. User did not provide input within the timeout period.
• 错误： Error getting voice input: error message

例子：

# French (default)
get_voice_input()

# English
get_voice_input(language="en")

# With custom timeout
get_voice_input(timeout=30)

API终点

POST/api/请求语音

创建新的语音输入请求（由MCP服务器调用）。

请求：

{"language": "fr"}

答复：

{"request_id": "abc123", "status": "pending"}

GET/api/待处理请求

获取待处理语音请求列表（由浏览器轮询）。

答复：

{
  "requests": [
    {"id": "abc123", "language": "fr"}
  ]
}

POST/api/索赔请求/{request_id}

请求待处理请求以防止重复处理。

答复：

{"status": "recording"}

POST/api/提交语音/{request_id}

提交录制的音频进行转录。

请求：

• 带音频文件的多部分形式（WAV格式，16kHz，单声道）

答复：

{
  "transcript": "user's spoken text",
  "status": "completed"
}

GET/api/result/{request_id}

获取转录结果（由MCP服务器轮询）。

答复：

{
  "status": "completed",
  "transcript": "user's spoken text",
  "error": null
}

配置

服务器配置

编辑 server.py:

WHISPER_HOST = "localhost"
WHISPER_PORT = 10300
PORT = 8766

Whisper型号

更改Whisper模型以实现速度/精度权衡：

# Faster, less accurate
--model tiny

# Balanced (default)
--model base

# Slower, more accurate
--model medium

SSL证书

生成自签名证书：

openssl req -x509 -newkey rsa:4096 \
  -keyout key.pem -out cert.pem \
  -days 365 -nodes \
  -subj "/CN=localhost"

故障排除

浏览器无法访问麦克风

检查HTTPS： 浏览器需要HTTPS才能访问麦克风

# Verify server is running with SSL
curl -k https://localhost:8766/health

检查权限： 在浏览器设置中授予麦克风访问权限

MCP服务器未加载

重新启动AI代理CLI：

# Exit and restart your AI command

检查.mcp.json路径：

# Verify path to mcp-server directory is correct
ls /path/to/mcp-hands-free/mcp-server/pyproject.toml

Whisper服务未响应

检查Whisper是否正在运行：

curl http://localhost:10300/

查看怀俄明州协议：

# Should show Wyoming service info
curl http://localhost:10300/v1/services

语音输入超时

检查浏览器是否打开： 确保已加载voice-input.html

检查轮询： 打开浏览器控制台，验证无错误

检查网络： 确保浏览器可以访问FastAPI服务器

文件

mcp-hands-free/
├── mcp-server/                    # MCP server package
│   ├── pyproject.toml
│   └── src/claude_voice_mcp/
│       ├── __init__.py            # Entry point
│       ├── server.py              # Tool definition
│       └── client.py              # HTTP client
├── server.py                      # FastAPI coordination server
├── static/
│   └── voice-input.html           # Browser recording interface
├── requirements.txt               # Python dependencies
├── .gitignore
└── README.md

安全须知

• 自签名证书 -浏览器将发出警告，单击“接受”
• 无身份验证 -使用防火墙或VPN限制访问
• 内存存储 -临时存储在内存中的语音请求
• 自动清理 -转录后删除的音频文件

高级用法

多语言支持

动态切换语言：

# Ask for French input
get_voice_input(language="fr")

# Ask for English input
get_voice_input(language="en")

自定义超时

调整超时时间以获得更长的语音输入：

# Wait up to 2 minutes
get_voice_input(timeout=120)

与其他MCP工具集成

将语音输入与其他MCP服务器相结合：

You: Get my next request via voice
[speaks] "What's in my vault?"
AI: [uses voice input tool, then vault MCP tool to query]

资源

• 模型上下文协议: https://github.com/anthropics/mcp
• 耳语: https://github.com/openai/whisper
• 怀俄明州议定书: https://github.com/rhasspy/wyoming
• 克劳德代码CLI: https://claude.com/claude-code（经过测试的MCP客户端）

兼容性

此MCP服务器遵循标准 模型上下文协议 规范，并应适用于任何兼容MCP的客户端：

• ✅ 克劳德代码CLI -经过全面测试并正常工作
• 🔜 其他MCP客户端 -应该开箱即用（Gemini、Qwen、自定义实现）

如果您在其他MCP客户端上测试了这一点，请打开一个问题来分享您的经验！

许可证

MIT许可证-个人和商业用途免费。