Voice Command

Voice-Command

[](https://github.com/AIWander/Voice-Command/actions/workflows/ci.yml) [](https://opensource.org/licenses/Apache-2.0) [](https://www.python.org/downloads/)

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](#the-voice-app-windows) 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

1. You hear a series of beeps. That's the AI's "I'm listening, your turn" cue.
2. You talk. Say what you want done. Anything your AI has the tools and authorization to handle counts.
3. 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…")
4. 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](#the-voice-app-windows).

---

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:

1. Grab the right voice-mcp.exe for your computer (ARM64 or x64) from the latest release
2. Drop it somewhere sensible (usually %LOCALAPPDATA%\CPC\servers\)
3. 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
4. Clone this repo and install the Python pieces
5. Write you a START_VOICE_SERVER.bat you can double-click whenever you want to talk
6. Walk you through restarting your AI client and starting the listener
7. 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:

1. 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).
2. Installs Python listening-server dependencies with pip install -r requirements.txt (skip with -SkipPython if you only want to talk, not listen).
3. 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.
4. For Codex (TOML), prints the snippet to append manually — PowerShell can't round-trip TOML safely.
5. 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 — 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 python@3.11 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](docs/VOICE_SYSTEM.md) — 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 also pauses the conversation. The switch back to listening is triggered by the end of playback, not the end of the AI's response — so while you have the voice paused, the mic stays off and the ready-beep waits. Unpause, let it finish, and listening starts on its own.
• 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, a

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AIWander
• Source: AIWander/Voice-Command
• License: Apache-2.0
• Homepage: https://voice.aiwander.ai

Install and usage instructions live in the source repository linked above.