# Voice Command > Local voice input/output layer for authorized MCP clients; adds speech without adding new tool privileges - **Type:** MCP server - **Install:** `agentstack add mcp-aiwander-voice-command` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [AIWander](https://agentstack.voostack.com/s/aiwander) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [AIWander](https://github.com/AIWander) - **Source:** https://github.com/AIWander/Voice-Command - **Website:** https://voice.aiwander.ai ## Install ```sh agentstack add mcp-aiwander-voice-command ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://github.com/AIWander) (Copy Paste Compute)** and the free core trio with [AI-Hands](https://github.com/AIWander/AI-Hands) and [Programmer-Wander](https://github.com/AIWander/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](https://github.com/SYSTRAN/faster-whisper) to understand what you say (running fully on your own computer — your voice doesn't go to the cloud) and [edge-tts](https://github.com/rany2/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`](https://github.com/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`](https://github.com/AIWander/ops)** — file and shell operations: read/write files, run commands, manage processes - **[AI-Hands](https://github.com/AIWander/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**](https://github.com/AIWander/Voice-Command/releases/latest) 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`](https://github.com/AIWander/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](https://github.com/AIWander/Voice-Command/releases/latest) 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`](https://github.com/AIWander/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`](https://github.com/AIWander/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](https://www.python.org/downloads/) - **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](https://ffmpeg.org/download.html) 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`: ```powershell .\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: ```bash pip install -r requirements.txt ``` On macOS, install the native audio prerequisites first: ```bash 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](https://www.lfd.uci.edu/~gohlke/pythonlibs/#pyaudio). On macOS, install Homebrew `portaudio` before installing Python dependencies: ```bash brew install portaudio ``` ### ffmpeg `winget install Gyan.FFmpeg`, or download from [ffmpeg.org](https://ffmpeg.org/download.html). 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`](https://github.com/AIWander/voice) repo has a Linux fork with the equivalent install steps. --- ## Running it Start the voice server: ```bash 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: ```bash ./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](https://github.com/AIWander) - **Source:** [AIWander/Voice-Command](https://github.com/AIWander/Voice-Command) - **License:** Apache-2.0 - **Homepage:** https://voice.aiwander.ai Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-aiwander-voice-command - Seller: https://agentstack.voostack.com/s/aiwander - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.