stt -linux

This MCP server provides local speech-to-text capabilities for Linux by running inside a Docker container. The server exposes a transcribe tool via the MCP protocol, which can inject transcribed text into Claude Code running in a Tmux session. It uses the Right Ctrl key as a push-to-talk trigger, reading keyboard events from /dev/input and recording audio from /dev/snd. The server is Linux-only due to the dependency on host devices and is designed to operate in a self-contained Docker environment for easy isolation and reproducibility. You can either run the server inside Docker for an isolated setup or use the standalone mode in a Tmux session without MCP in a pinch, but the MCP flow provides the full integration with Claude Code for automatic transcription into Claude’s input stream.

Prerequisites:

• Docker Engine or Docker Desktop installed on a Linux machine.
• Git for cloning the repository.
• TMUX installed on the host (for integrating with Claude Code and standalone mode).

Installation steps:

1. Clone the repository and navigate into it: git clone https://github.com/marcindulak/stt-mcp-server-linux cd stt-mcp-server-linux

2. Build the Docker image for the MCP server: bash scripts/build_docker_image.sh

3. Download the Whisper model (tiny) to the expected directory inside the container: bash scripts/download_whisper_model.sh

4. Run the MCP server container: docker run -i --name stt-mcp-server-linux stt-mcp-server-linux

5. (Optional) If you want to test standalone mode, you can run the container with appropriate environment and then start the standalone service inside a Tmux session as documented in the repo README.

Notes and tips:

• The MCP server creates the directory ~/.stt-mcp-server-linux on first run. This is used to persist models and configuration across restarts.
• If you encounter initialization delays, check container logs with: docker logs stt-mcp-server-linux to verify the server is waiting for the Right Ctrl press and that transcription is active.
• Standalone mode is useful for testing without Claude Code, but MCP mode is required for automatic text injection into Claude’s input stream.
• The Right Ctrl push-to-talk workflow relies on accessing /dev/input keyboard devices and /dev/snd for the microphone. Ensure proper permissions and that the host devices are accessible to the container.
• When using Docker, make sure to expose or mount any necessary host devices if you modify the docker run options (e.g., --device /dev/input:/dev/input:ro and similar) depending on your environment.