clvoice-mcp

Hold Ctrl + `, talk, release. The audio is recorded (ffmpeg) → transcribed (Groq Whisper, ~1s) → filler words cleaned up (Groq LLM) → pasted into the focused input for you to edit before sending. Nothing runs automatically — you stay in control.

TypeScript. Windows (microphone via DirectShow/dshow). Runs as an MCP server that Claude Code keeps alive for the whole session.

How it works

HOLD Ctrl+`  ──►  ffmpeg records mic  ──►  release
      │                                      │
      ▼                                      ▼
  🔴 recording        Groq Whisper (STT) ─► ✨ clean fillers (Groq LLM)
                                             │
                                             ▼
                          paste into focused input ─► you edit ─► Enter

Two ways to trigger:

1. Push-to-talk hotkey (recommended, hands-free). The MCP server hosts a global hotkey watcher for the whole session.

2. MCP tool voice_listen — Claude calls it when you ask (e.g. "listen to me").

Important: the transcript is not returned to Claude and is never auto-executed — it only lands in your input box. You edit, then press Enter to send.

Related MCP server: Claude Voice Commands

Features

• 🎙️ Push-to-talk dictation (hold to talk, release to send)

• ⚡ Fast STT via Groq Whisper (~1s); Gemini as an alternative

• 🎚️ Audio preprocessing (high-pass + loudness normalize) + clip-safe start/stop for cleaner capture

• ✨ Filler-word cleanup ("à, ừm, ờ...") + punctuation via a Groq LLM (context-aware, never executes your text)

• 📋 Clipboard + auto-paste into whatever window is focused

• 🔊 Audio beeps (start / stop / done) + on-terminal status line

• 🧩 Self-hosted in the MCP server — no separate window, single-instance lock + takeover across multiple Claude Code windows

• 🪟 One-command setup (setup.ps1)

Requirements

• Node.js ≥ 18

• ffmpeg on PATH (ffmpeg -version) — https://ffmpeg.org/download.html

• A working microphone

• Groq API key (default, free): https://console.groq.com/keys — or a Gemini API key: https://aistudio.google.com/apikey

Quick setup (Windows)

cd clvoice-mcp
powershell -ExecutionPolicy Bypass -File setup.ps1

The script installs deps, builds, detects your mic, asks for a Groq key, registers the MCP server (user scope), and adds the status line. Hotkey + cleanup are on by default, so nothing else to configure. Then restart Claude Code.

Non-interactive:

powershell -ExecutionPolicy Bypass -File setup.ps1 -GroqKey "<key>" -MicDevice "<mic>" -Lang vi
# -Lang: vi (default), en, or auto  |  add -NoStatusLine to skip the status line

Manual setup

npm install
npm run build           # produces dist/index.js
ffmpeg -list_devices true -f dshow -i dummy   # find your mic name
claude mcp add clvoice --scope user ^
  --env GROQ_API_KEY=<KEY> ^
  --env "CLVOICE_MIC_DEVICE=<MIC>" ^
  -- node <ABSOLUTE-PATH>\dist\index.js

Groq STT, hotkey, and cleanup are all default-on, so they don't need env vars. To use Gemini instead: add --env CLVOICE_STT=gemini --env GEMINI_API_KEY=....

Configuration (environment variables)

Usage

Hotkey (push-to-talk)

**Hold Ctrl + **, speak, release. You'll hear a high beep (recording), a low beep (processing), then a short beep (done) as the text is pasted. Change the key in scripts/clvoice-hotkey.ps1 (-Key, -NoCtrl, -Alt, -Shift`).

MCP tools

• voice_listen({ seconds?, language? }) — record, transcribe, paste into the input. Does not return the transcript.

• list_audio_devices() — list mic names for CLVOICE_MIC_DEVICE.

Status line (on the Claude Code terminal)

setup.ps1 adds this automatically. Manual:

// ~/.claude/settings.json
"statusLine": {
  "type": "command",
  "command": "node \"<ABS>\\scripts\\clvoice-statusline.cjs\"",
  "padding": 0,
  "refreshInterval": 1
}

Shows 🔴 recording → ⏳ transcribing → ✨ processing, hidden when idle. The wrapper preserves any existing status line. ~1s refresh (Claude Code limit); beeps are instant.

Privacy

Audio is sent to the cloud STT provider (Groq or Google) to be transcribed. Don't use it for sensitive content. A local/offline STT is out of scope for v1.

Troubleshooting

Limitations (v1)

Windows-only · cloud STT (needs internet) · status line capped at ~1s refresh · the recording status is shared across all Claude Code windows (cosmetic).

License

MIT