Voice-Command

Talk to your AI. Hear it work.

Part of CPC (Copy Paste Compute) and the free core trio with AI-Hands and Programmer-Wander.

Names you will see: product and repository = Voice-Command; MCP server key = voice; Rust wrapper = voice-mcp.exe; Windows companion = Voice App; listening service = the Python voice server included in this repository.

Voice-Command lets you voice-control your AI end-to-end. You say what you want done — Claude chat or another AI does it, using whatever tools, connectors, and MCPs it has access to — and narrates what it's doing as it goes. Voice adds no new privileges; it only invokes tools the user has already installed and enabled. Sensitive actions should require confirmation. If it can do it typed, you can ask for it spoken.

Under the hood it uses faster-whisper to understand what you say (running fully on your own computer — your voice doesn't go to the cloud) and edge-tts to speak responses back through Microsoft Edge's online text-to-speech service. It also reads the feel of how you say things — excited, hesitant, frustrated — and passes that along so the AI can respond more naturally.

What stays local

Voice-Command's microphone capture, speech-to-text, silence detection, noise filtering, emotion detection, and audio playback run on your machine. The listening server binds to localhost:5123, not your LAN.

Text-to-speech currently uses edge-tts, which calls Microsoft Edge's online TTS service. Your AI may also reach out for its own model calls (Claude pings Anthropic, ChatGPT pings OpenAI, and so on), and tools it calls might reach out too (web search, email connectors). For a fully offline loop, pair this with a local model and replace edge-tts with a local TTS backend.

Safe Use / Permission Model

AIWander tools are local, user-authorized MCP capability surfaces. They do not grant an AI new permissions by themselves. They expose tools the user explicitly installs and enables. Sensitive actions should be confirmed by the user, credentials should stay in the OS keyring or local vault, and demos should use mock data.

Platform support

Windows is the primary supported platform (x64 and ARM64), and it now gets the Voice App — a single window that handles speech playback and listening, with pause/resume from your headset button. See The Voice App below. macOS has an experimental source install path: the Python listener runs with Homebrew portaudio, server.py uses the built-in afplay player for TTS playback, and the Rust voice-mcp wrapper builds on both Intel and Apple Silicon — macOS uses the terminal listening server rather than the Voice App for now. For Linux, see the upstream AIWander/voice repo — there's a community fork there with Linux support.

Works with

Voice-Command is a STDIO MCP server, so it plugs into any AI client that speaks MCP. That includes:

Claude (chat) — Claude Desktop and the web app
Cowork — Claude's desktop agent
Claude Code — the CLI coding agent
Codex CLI — OpenAI / GPT
Gemini CLI — Google
LM Studio — for running local models (Llama, Qwen, Mistral, whatever you've loaded up)
Anything else that can call a STDIO MCP server — the protocol is the only requirement

It doesn't care which model is on the other end. If your AI of choice can call MCP tools, you can talk to it.

How a turn works

You hear a series of beeps. That's the AI's "I'm listening, your turn" cue.
You talk. Say what you want done. Anything your AI has the tools and authorization to handle counts.
The AI works — and tells you out loud what it's doing as it goes. ("Checking your calendar… found three events tomorrow… drafting the reply…")
You hear the beeps again. The AI's done with that turn. Your move.

One thing to know up front: the audio flow is one turn at a time. With the basic terminal listener, the beeps are the only handoff and you can't cut the AI off by voice. The Voice App (below) adds real controls — Pause to hold the AI, Interrupt to take the floor immediately, and Stop to end — from your headset's play/pause button or the app window. See The Voice App.

How to end a session

Just tell the AI you're done — "I'm done talking," "let's talk later," "bye for now," anything in that family. Or hit the stop button in your AI's UI. Both work; saying it out loud is more graceful.

What you can actually ask for

Anything your AI has the tools to do. A few examples to give you the shape of it:

"Check my calendar for tomorrow and read me what's on it." → uses your Google Calendar connector
"Search the web for the latest on [topic] and summarize." → uses web search
"Read me the README in this folder." → uses local filesystem
"Find the file we were editing yesterday and fix the bug we talked about." → uses filesystem + memory of past chats
"Draft an email to Sarah saying I'll be ten minutes late and ask me before sending." → uses your email connector
"Run the test script and tell me when it's done." → uses shell access

The voice layer doesn't add capabilities — it just changes how you reach them. Whatever connectors, MCPs, and tools you've already hooked up to your AI all work the same. You're just using your mouth instead of your keyboard. Treat voice commands the same way you treat typed commands: if your AI has tools that can send email, edit files, run shell commands, or trigger automations, those tools can also be invoked by speech.

Pairs nicely with

Voice-Command is most useful when your AI also has hands. These three companion MCPs are all local tools that live on your computer, all callable by voice once Voice-Command is wired up:

ops — file and shell operations: read/write files, run commands, manage processes
AI-Hands — browser automation, Windows UI control, vision/OCR; its binary and MCP server key remain hands

Install any combination. Voice-Command is the mouth and ears; these are the rest of the body. These tools run locally, but the actions they perform can still touch files, browsers, APIs, email, or shell commands depending on what you have enabled.

The easiest way: download the installer

Grab the signed, self-contained installer for your PC from the latest release and double-click it:

Your PC	Download
Intel / AMD (x64)	`CPC-Voice-Setup-x64.exe`
ARM64 (Snapdragon, etc.)	`CPC-Voice-Setup-arm64.exe`

It bundles everything — a private Python runtime, the speech-to-text model, and the voice.exe MCP wrapper — so there's nothing else to install, and no internet needed at install time. It wires the voice MCP server into Claude Desktop and Claude Code for you and adds a shortcut. Every binary and installer is Authenticode-signed (publisher: Joseph Wander).

Not on Windows, or want to wire it by hand? Use one of the source paths below.

The easy way to install: ask your AI to do it

This is the whole point. You shouldn't need a CS degree to get this running.

If you have Claude Desktop with ops installed, Cowork, Claude Code, Codex CLI, or Gemini CLI open right now, copy this and paste it to your AI:

https://github.com/AIWander/Voice-Command — Can you install this MCP for us to use here, set up the voice listening server, and make me a .bat to launch it. Walk me through any restart or step I need to do. Tell me clearly when everything's installed and we're ready to talk.

Your AI will:

Grab the right voice-mcp.exe for your computer (ARM64 or x64) from the latest release
Drop it somewhere sensible (usually %LOCALAPPDATA%\CPC\servers\)
Wire it into your AI client's MCP config file — your existing setup is preserved, and a timestamped backup is made first, so nothing breaks
Clone this repo and install the Python pieces
Write you a START_VOICE_SERVER.bat you can double-click whenever you want to talk
Walk you through restarting your AI client and starting the listener
Tell you when everything's ready

Then you're talking. Literally.

After install — starting voice mode is just asking for it. Once everything's running and you've restarted your AI client, you don't need to paste anything else. On Claude chat or Cowork, just ask the AI "let's talk" or "start voice mode" — it'll fire up the listening loop and you'll hear the beeps. Same on other MCP-capable clients.

Don't forget the connector toggle. In Claude Desktop and Cowork, MCP connectors have an on/off switch in Settings → Connectors. Make sure the voice MCP entry is toggled on after the restart, otherwise the AI won't see the speak/listen tools.

No Python on the machine? Voice-Command's listening server runs on Python 3.11. If you don't have Python installed, your AI can fetch it for you using ops — just ask. Without Python, the AI can still talk to you (text-to-speech works), but it can't hear you (no listening server). Both halves need Python. On Windows ARM64 you'll specifically want x64 Python 3.11 since some dependencies don't ship ARM64 wheels yet.

Don't have an operator MCP yet? ops is the recommended one — public, lightweight, does file/shell work for any AI you want to give hands to. Install ops first, then come back and paste the prompt above. If you have local, programmer, or another operator MCP already, those work too.

If your AI doesn't have access to your filesystem and shell, scroll down to Manual installation below — or run install.ps1 yourself in a PowerShell window.

What it looks like when it's running

Screenshot of the voice listening server in action — coming soon. Once you've installed Voice-Command, the server window will look something like this, with a beep cue when it's your turn and a live RMS readout while you talk.

What you'll need on your computer

Windows 10 or 11, or macOS for the experimental source install path
Python 3.11 or newer — download here
A microphone — built-in or USB, doesn't need to be fancy
PortAudio — a library that lets Python use your mic; usually installs automatically on Windows, and should be installed with Homebrew on macOS
ffmpeg — for playing back the AI's voice; free, grab it here

If any of those words look scary, don't worry — your AI can handle all of this for you using the prompt at the top.

Installer script (`install.ps1`)

If your AI can run scripts but isn't great at multi-step shell flows, point it at install.ps1:

.\install.ps1

What it does, in order:

Detects your CPU architecture (ARM64 or x64) and downloads the matching voice-mcp.exe from the latest release to %LOCALAPPDATA%\CPC\servers\ (override with -InstallDir).
Installs Python listening-server dependencies with pip install -r requirements.txt (skip with -SkipPython if you only want to talk, not listen).
Detects which MCP clients you have installed (Claude Code, Claude Desktop, Codex Windows, Gemini CLI, LM Studio) and adds a voice entry to each — backed up first.
For Codex (TOML), prints the snippet to append manually — PowerShell can't round-trip TOML safely.
Ends with a clear "say hi out loud and then listen for me" check so you know the round-trip works.

Useful flags:

-Verify — report state only, change nothing
-DryRun — print what would happen
-SkipPython — binary + configs only
-InstallDir <path> — install the binary somewhere other than %LOCALAPPDATA%\CPC\servers

Manual installation (if you'd rather drive yourself)

Clone the repo, then:

pip install -r requirements.txt

On macOS, install the native audio prerequisites first:

brew install [email protected] portaudio ffmpeg
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -r requirements.txt

PortAudio

pip install pyaudio usually just works on Windows. If it complains, grab a wheel from the unofficial PyAudio wheels page.

On macOS, install Homebrew portaudio before installing Python dependencies:

brew install portaudio

ffmpeg

winget install Gyan.FFmpeg, or download from ffmpeg.org. Make sure it's on your PATH, or set the VOICE_FFMPEG_PATH environment variable to point at it.

On macOS, brew install ffmpeg is enough for the listener stack. The Python MCP fallback uses macOS afplay directly for generated MP3 speech, so it does not need simpleaudio for playback there.

Setting up on Linux? The upstream AIWander/voice repo has a Linux fork with the equivalent install steps.

Running it

Start the voice server:

python voice_server.py

It runs at http://localhost:5123. On Windows, you can also just double-click START_VOICE_SERVER.bat. On macOS, run:

./START_VOICE_SERVER.sh

You mostly won't touch the endpoints directly — the AI calls them for you — but here they are:

Endpoint	What it does
`GET /status`	Health check
`POST /listen?timeout=30`	Records, transcribes, reads emotion

Optional knobs you can pass to /listen:

skip_emotion=true — don't bother with emotion detection
skip_filter=true — turn off noise filtering
silence_timeout=4.0 — how long of a pause before it stops listening
min_speech_duration=3.0 — how long you need to talk before it'll consider stopping
rms_threshold=100 — how loud counts as "talking" (20–500)

The Voice App (Windows)

The terminal listener works, but on Windows there's a nicer way: the Voice App. One small window replaces the terminal entirely and handles both halves of the conversation:

Driving it from an AI agent? See the Voice System operating guide — the pause/interrupt/stop control model, the HTTP API on :5123, the playback backends, and the rules for running a clean voice exchange.

START_VOICE_APP.bat

What you get:

Pause the AI's voice with your headset button. The app registers as a real Windows media session, so the play/pause button on your earbuds, headset, or keyboard pauses and resumes Claude's voice exactly like it would Spotify. There's a pause button in the window too (it turns amber while paused), and spacebar works.
Pausing holds the response in place. The regular listener and ready-beep wait, while the no-beep interruption listener remains armed for your selected words. Resume continues from the same position.
Say umm to take the floor without reaching for the widget. The app pauses, the regular listener beeps, and you can add new information. Silence resumes the same audio; new speech gives the AI the prior response and playback position so it can answer the interruption without forgetting its unfinished point. The widget lets you replace umm with your own comma-separated phrases.
The AI keeps working while you listen. Speech is queued and played in the background, so the AI can keep using tools — or even finish its whole response — while you're still hearing it.
Status at a glance: speaking / paused / listening state, playback progress, live mic level, and a color-coded transcript of the conversation.

It works on both x64 and ARM64 Windows (on ARM64, build the .venv from x64 Python 3.11 — same note as the listener, ctranslate2 doesn't ship ARM64 wheels). Native media-session support uses the winsdk package; if it isn't available the app falls back to an equivalent player with a media-key hook, and everything still works.

The app serves the same http://localhost:5123 API as the terminal listener (so the MCP wrapper auto-detects it), plus playback and interruption endpoints: POST /say, /pause, /resume, /toggle, /interrupt (/skip alias), /stop, /interruption-listener/config, and GET /playback or /interruption-listener.

On macOS, stick with ./START_VOICE_SERVER.sh — the Voice App's media-session integration is Windows-only for now.

Running headless on Windows

If you don't want a console window sitting on screen, swap python.exe for pythonw.exe (the windowless Python host) and launch via PowerShell's hidden window flag:

Start-Process -FilePath "C:\Python311-x64\pythonw.exe" `
              -ArgumentList '"C:\path\to\Voice-Command\voice_server.py"' `
              -WorkingDirectory "C:\path\to\Voice-Command" `
              -WindowStyle Hidden

The server still listens on localhost:5123 and reads voice.config.toml from its working directory — there's just no console to see or close. Cold start is ~6 seconds while the speech model loads, then it's idle until /listen is called.

Resource cost at idle: ~250 MB RAM, zero CPU.

To persist across reboots, drop a shortcut to that PowerShell line in shell:startup, or register a Scheduled Task at user logon (action: pythonw.exe, args: "path\to\voice_server.py", run hidden as user).

To stop it: Stop-Process -Name pythonw -Force (caution: kills all pythonw — narrow by PID if you have other Python tools running).

Tweaking the defaults

Drop a file called voice.config.toml next to the script (or set VOICE_CONFIG_PATH to point at it). A voice.config.example.toml is included in this repo — copy it and edit. Tuned defaults for natural back-and-forth conversation:

[listen]
silence_timeout_secs = 3.0
min_speech_duration_secs = 2.0
rms_threshold = 100
noise_filter_enabled = true
pre_record_enabled = true

[interruption_listener]
enabled = true
trigger_phrases = ["umm"]
listen_while_paused = true
window_secs = 1.5
rms_threshold = 100.0
cooldown_secs = 1.5
empty_handoff_timeout_secs = 5.0

Earlier defaults of 4.0/3.0 felt sluggish in conversational use. For typing-replacement / dictating long prose, raise silence_timeout_secs to 5.0+ so natural pauses don't cut you off.

It looks for config in this order:

VOICE_CONFIG_PATH environment variable
./voice.config.toml (current directory)
~/.config/voice/voice.config.toml

How an MCP client connects to it

server.py is a thin wrapper that exposes three tools to any MCP client:

speak — say something out loud
listen_for_speech — listen for what the user says (waits for any paused/playing speech to finish first)
playback_control — pause, resume, skip, or stop the voice playback (Voice App only)
start_voice_mode — kick off a back-and-forth conversation

For everyday use, there's a Rust version of that wrapper (voice-mcp.exe on Windows, voice-mcp on macOS) that's faster and more stable. Windows builds come as release downloads (ARM64 + x64), and the release workflow is set up to publish macOS Intel + Apple Silicon builds on future tags. The Python server.py works as a fallback if you'd rather not use the binary.

Config snippets per client

Copy the snippet for your AI client into the file path shown. install.ps1 does the wiring for you on JSON clients — these snippets are the fallback if it can't reach the file (or if you'd rather edit by hand). The snippets below use C:\Users\YOUR-USER\AppData\Local\CPC\servers\voice-mcp.exe; replace YOUR-USER with your Windows username, or use the exact path printed by install.ps1. On macOS, point the command to your built or downloaded voice-mcp binary, for example /usr/local/bin/voice-mcp.

Claude Code — `%USERPROFILE%\.claude\mcp.json`

{
  "mcpServers": {
    "voice": {
      "command": "C:\\Users\\YOUR-USER\\AppData\\Local\\CPC\\servers\\voice-mcp.exe"
    }
  }
}

Claude Desktop — `%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "voice": {
      "command": "C:\\Users\\YOUR-USER\\AppData\\Local\\CPC\\servers\\voice-mcp.exe"
    }
  }
}

Codex (Windows app) — `%USERPROFILE%\.codex\config.toml`

[mcp_servers.voice]
command = "C:\\Users\\YOUR-USER\\AppData\\Local\\CPC\\servers\\voice-mcp.exe"
cwd = "C:\\Users\\YOUR-USER\\AppData\\Local\\CPC\\servers"

install.ps1 doesn't auto-edit this one — TOML round-tripping in PowerShell is fragile. Append the block manually; it's two lines.

Gemini CLI — `%USERPROFILE%\.gemini\settings.json`

{
  "mcpServers": {
    "voice": {
      "command": "C:\\Users\\YOUR-USER\\AppData\\Local\\CPC\\servers\\voice-mcp.exe"
    }
  }
}

(Add to the existing mcpServers object alongside your other entries — don't replace the whole file.)

LM Studio — `%USERPROFILE%\.lmstudio\mcp.json`

{
  "mcpServers": {
    "voice": {
      "command": "C:\\Users\\YOUR-USER\\AppData\\Local\\CPC\\servers\\voice-mcp.exe"
    }
  }
}

Other MCP-speaking clients work too. If your AI's client isn't above but accepts STDIO MCP servers, use whichever JSON snippet matches — the three lines that matter are "voice", "command", and the absolute path to voice-mcp.exe.

Reloading your client (usually not required)

Most MCP clients pick up new STDIO servers on the next tool-list refresh — no full restart. If your client doesn't see the voice, listen_for_speech, or speak tools after a minute, then restart it. Claude Desktop and Codex Windows app sometimes need a full quit-and-reopen on first wire-up.

Verify by saying hi

Skip the formal health check — just use the tools themselves. Ask your AI:

"Say hi out loud and then listen for me."

If you hear the AI greet you and then hear the listening beep, you're wired up end-to-end. Talk back and confirm it transcribed you. If something's broken, you'll know exactly which half failed:

No voice → TTS half is off (likely ffmpeg missing or audio output device wrong)
Voice but no beep → MCP wiring worked for speak, not for listen (config has the entry but maybe server.py isn't running)
Beep but no transcription → microphone permission off (see the warning earlier) OR voice_server.py not running OR mic not picked up
Full round-trip works → you're done. Talk away.

Building `voice-mcp` from source

The Rust source for voice-mcp.exe lives in voice-mcp/ at the root of this repo. To build it yourself instead of grabbing the prebuilt binary from releases:

cd voice-mcp
cargo build --release

The compiled binary lands in voice-mcp/target/release/voice-mcp.exe on Windows and voice-mcp/target/release/voice-mcp on macOS. Move it wherever you like and point claude_desktop_config.json at it.

On Windows, scripts\build-x64.bat is the reproducible x64 path. It loads the Visual Studio x64 toolchain, builds x86_64-pc-windows-msvc in C:\temp\rust-build-staged\voice-command, and stages dist\voice-mcp-x64.exe without replacing an installed server.

You'll need a Rust toolchain installed. Building takes a couple of minutes on a modern machine. The release workflow on tag push builds ARM64 and x64 binaries for Windows and macOS automatically.

What's in the box

voice_server.py — the standalone HTTP server that does the actual listening, transcribing, and tone-reading
server.py — the MCP wrapper your AI client talks to; calls voice_server.py for input and edge-tts for output
response_analyzer.py — separate analyzer that reads emotion from text the AI says back
emotion_config.json — knobs for the response analyzer (which words count as excited, hedging, etc.)
play_audio.ps1 — Windows audio playback helper
START_VOICE_SERVER.bat — Windows launcher

Environment variables

Variable	What it's for	Default
`VOICE_CONFIG_PATH`	Where your `voice.config.toml` lives	Auto-discovered
`VOICE_FFMPEG_PATH`	Where ffmpeg lives	Found via PATH
`VOICE_EMOTION_LOG_DIR`	Where emotion logs get written	`~/.voice/logs/`
`VOICE_TRANSCRIPT_LOG_PATH`	Rolling transcript log path for voice checkpoints	`%LOCALAPPDATA%\Voice-Command\voice_sessions\rolling_log.jsonl`

Troubleshooting

pip install pyaudio fails on Windows ARM64. PyAudio doesn't ship native ARM64 wheels yet. Install x64 Python 3.11 alongside your ARM64 Python (Windows 11 ARM64 runs x64 Python under emulation just fine), and use the x64 interpreter to run voice_server.py. Or grab a precompiled ARM64 wheel from the unofficial PyAudio wheels page.

ffmpeg not found. Either add ffmpeg to your PATH or set the VOICE_FFMPEG_PATH environment variable to the full path of ffmpeg.exe. On Windows, winget install Gyan.FFmpeg is the easiest install.

Python 3.13 wheel mismatch. faster-whisper and pyaudio don't have Python 3.13 wheels yet at the time of writing. Stick with Python 3.11 or 3.12 until the dependency tree catches up.

Microphone permission denied. Check Windows Settings → Privacy & security → Microphone, and make sure both "Microphone access" and "Let apps access your microphone" are on. If you launched voice_server.py from a terminal, that terminal needs mic permission too.

MCP connector toggle is off. In Claude Desktop, Settings → Connectors → make sure the voice (Rust) or voice-command (Python) toggle is ON. If neither is on, your AI won't see the tools.

voice-command MCP can't reach the listener. The MCP wrappers (voice-mcp.exe or server.py) talk to voice_server.py over localhost:5123. Make sure the listening server window is open and showing output. Restart START_VOICE_SERVER.bat if it's quiet.

Whisper model download stalls on first run. The first time voice_server.py starts, faster-whisper downloads the Whisper model (~150 MB for the base model). This can stall on slow connections. Run voice_server.py once at install time and let the download finish before trying voice mode in your AI client.

License

Apache 2.0 — see LICENSE.

Voice Command

README

Voice-Command

What stays local

Safe Use / Permission Model

Platform support

Works with

How a turn works

How to end a session

What you can actually ask for

Pairs nicely with

The easiest way: download the installer

The easy way to install: ask your AI to do it

What it looks like when it's running

What you'll need on your computer

Installer script (`install.ps1`)

Manual installation (if you'd rather drive yourself)

PortAudio

ffmpeg

Running it

The Voice App (Windows)

Running headless on Windows

Tweaking the defaults

How an MCP client connects to it

Config snippets per client

Claude Code — `%USERPROFILE%\.claude\mcp.json`

Claude Desktop — `%APPDATA%\Claude\claude_desktop_config.json`

Codex (Windows app) — `%USERPROFILE%\.codex\config.toml`

Gemini CLI — `%USERPROFILE%\.gemini\settings.json`

LM Studio — `%USERPROFILE%\.lmstudio\mcp.json`

Reloading your client (usually not required)

Verify by saying hi

Building `voice-mcp` from source

What's in the box

Environment variables

Troubleshooting

License

Comments (0)

Voice Command

README

Voice-Command

What stays local

Safe Use / Permission Model

Platform support

Works with

How a turn works

How to end a session

What you can actually ask for

Pairs nicely with

The easiest way: download the installer

The easy way to install: ask your AI to do it

What it looks like when it's running

What you'll need on your computer

Installer script (install.ps1)

Manual installation (if you'd rather drive yourself)

PortAudio

ffmpeg

Running it

The Voice App (Windows)

Running headless on Windows

Tweaking the defaults

How an MCP client connects to it

Config snippets per client

Claude Code — %USERPROFILE%\.claude\mcp.json

Claude Desktop — %APPDATA%\Claude\claude_desktop_config.json

Codex (Windows app) — %USERPROFILE%\.codex\config.toml

Gemini CLI — %USERPROFILE%\.gemini\settings.json

LM Studio — %USERPROFILE%\.lmstudio\mcp.json

Reloading your client (usually not required)

Verify by saying hi

Building voice-mcp from source

What's in the box

Environment variables

Troubleshooting

License

Comments (0)

Installer script (`install.ps1`)

Claude Code — `%USERPROFILE%\.claude\mcp.json`

Claude Desktop — `%APPDATA%\Claude\claude_desktop_config.json`

Codex (Windows app) — `%USERPROFILE%\.codex\config.toml`

Gemini CLI — `%USERPROFILE%\.gemini\settings.json`

LM Studio — `%USERPROFILE%\.lmstudio\mcp.json`

Building `voice-mcp` from source