Skip to main content
Glama
tvtdev94

clvoice-mcp

by tvtdev94
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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

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)

Variable

Required

Default

Description

CLVOICE_STT

❌

groq

STT engine: groq (fast, ~1s) or gemini.

CLVOICE_LANG

❌

vi

Spoken language: vi (default), en, or auto (detect VI/EN).

GROQ_API_KEY

✅ (for groq)

—

Groq API key — https://console.groq.com/keys

CLVOICE_GROQ_MODEL

❌

whisper-large-v3

Groq Whisper model. Default favors accuracy (esp. Vietnamese); set whisper-large-v3-turbo for ~1–2s faster transcription.

GEMINI_API_KEY

✅ (for gemini)

—

Gemini API key.

CLVOICE_GEMINI_MODEL

❌

gemini-2.5-flash

Gemini model (switch if a model 404s).

CLVOICE_MIC_DEVICE

❌

(first input)

Exact dshow mic name.

CLVOICE_FFMPEG_PATH

❌

ffmpeg

Path to the ffmpeg binary.

CLVOICE_HOTKEY

❌

true

Host the push-to-talk watcher in the server. 0 to disable.

CLVOICE_CLEAN

❌

true

Clean filler words via Groq LLM (+~0.4s, needs GROQ_API_KEY, fail-open). 0 to disable.

CLVOICE_CLEAN_MODEL

❌

llama-3.3-70b-versatile

Groq chat model for cleanup.

CLVOICE_AUTO_PASTE

❌

true

Auto-paste (Ctrl+V) into the focused window. false = clipboard only.

CLVOICE_DEFAULT_SECONDS

❌

15

Default record duration (MCP tool path).

CLVOICE_MAX_SECONDS

❌

60

Hard cap on record duration.

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

Symptom

Fix

ffmpeg not found

Install ffmpeg and add to PATH, or set CLVOICE_FFMPEG_PATH.

No mic / wrong mic

Run list_audio_devices (or ffmpeg -list_devices), set CLVOICE_MIC_DEVICE.

No beep / no status on first use

Server warms up a few seconds after Claude Code starts — wait, then try.

Hotkey stops after closing a window

Close all old Claude Code windows after changing env (server env is captured at spawn).

Empty transcription

Audio was silent/too short — speak clearly, increase duration.

Status shows stale state

Check %TEMP%\clvoice-debug.log for the last raw/final/clean line.

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

Available Tools

2 tools
list_audio_devicesList Audio Input DevicesA

List available microphone input device names so the user can set CLVOICE_MIC_DEVICE.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the action (list) and purpose but does not disclose any additional behavioral traits such as side effects, permissions, or return structure. For a simple read-only tool, this is minimally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with the verb 'List', no wasted words. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, no output schema, and low complexity, the description fully covers what an agent needs to know: it lists device names for a specific purpose. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so baseline is 4. The description does not need to add parameter info. It adds value by explaining the purpose, which is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it lists available microphone input device names. The verb 'list' matches the resource 'audio devices', and the purpose is specific. Sibling tool voice_listen is distinct, so no confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says the list is for setting CLVOICE_MIC_DEVICE, providing clear usage context. Does not include when-not or alternatives, but given the simple sibling relationship, it is adequate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

voice_listenVoice Listen (Vietnamese)A

Record the microphone for a few seconds, transcribe the speech (Vietnamese or English), and place the text into the user's input box (clipboard + optional auto-paste) for them to edit. It does NOT return the transcript and must NOT be executed: after calling, just confirm briefly and wait for the user's next (edited) message. Use when the user wants to dictate input.

ParametersJSON Schema
NameRequiredDescriptionDefault
secondsNoRecording duration in seconds (default 15, clamped to the server max).
languageNoSpoken language hint, default "vi" (Vietnamese).

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility. It discloses that the tool does not return a transcript and advises the agent to wait for user edits. However, the phrase 'must NOT be executed' is contradictory to 'after calling,' creating confusion about whether the agent should invoke the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively concise at three sentences, but the confusing instruction 'must NOT be executed' detracts from clarity and could be rephrased.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, side effect, and usage guidance adequately for a tool with only two parameters and no output schema. However, the ambiguous execution instruction and lack of detail on behavior when language is not supported reduce completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds value by noting defaults (15 seconds for 'seconds', 'vi' for 'language') and that 'seconds' is clamped to server maximum. This goes beyond the schema's parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: record microphone, transcribe Vietnamese or English speech, and place text into user's input box. It also specifies what it does not do (return transcript) and distinguishes from the sibling tool list_audio_devices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use when the user wants to dictate input' and instructs the agent to confirm briefly and wait for the user's next message after calling. However, it does not mention when to avoid using it (e.g., if user wants to transcribe a file).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observedlist_audio_devices
    • First observedvoice_listen
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: one for dictation and transcription, the other for listing audio devices. No overlap in functionality.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern: 'voice_listen' and 'list_audio_devices', with snake_case and clear action prefixes.

Tool Count5/5

Two tools is appropriate for the narrow scope of voice input: one to configure the device and one to capture input. The tool count matches the domain well.

Completeness4/5

The server covers the core needs (capture input, list devices). A minor gap is the lack of a tool to set the microphone device directly, but this is handled via environment variable.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tvtdev94/clvoice-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server