marcindulak/stt-mcp-server-linux

Functionality overview
Local speech-to-text MCP server for Linux.
The speech-to-text functionality can also be used in a standalone mode in Tmux, without relying on MCP.
Claude Code is required to run inside a Tmux session to enable the transcribed text injection into Claude's input stream.
The MCP server runs in a Docker container with access to host input and audio devices.
The server provides a transcribe tool accessible through MCP protocol.
When the tool is activated, the server monitors the Right Ctrl key for push-to-talk functionality.
Key press detection uses /dev/input keyboard devices.
Audio recording uses /dev/snd microphone device.
On Right Ctrl key release, speech-to-text transcription occurs (using Whisper tiny model by default).
The transcribed text is injected into Claude's input stream via Tmux send-keys.
The MCP server is Linux-only due to /dev device dependencies.
> [!WARNING]
> This project will create ~/.stt-mcp-server-linux directory.
Usage examples
The instructions follow below.
1. Install Docker Engine or Docker Desktop
2. Install Tmux.
If you are unfamiliar with, Tmux watch this YouTube tutorial and checkout out this cheat sheet for a shortcuts reference.
3. Clone this repository, and cd into it:
4. Build the Docker image of the MCP server:
5. Download the Whisper tiny model under ~/.stt-mcp-server-linux/whisper:
6. Configure Tmux, so ~/.tmux.conf contains at least:
MCP mode
In this mode, the local MCP server running in the Docker container exposes the transcribe tool.
The tool is activated from Claude Code, running in a Tmux session.
The tool sends the transcribed text into the Tmux session's input buffer.
7. Install Claude Code
8. Add the MCP server to Claude (MCP client).
Navigate to any of your Claude directories.
Verify the Claude connection to the MCP server with:
Expected output:
> [!NOTE]
> The addition the MCP server needs to be performed only once, because the server is added with the --scope user.
> The first time setup is now complete!
9. Navigate to any of your Claude directories, start Claude in a new Tmux session stored under ~/.stt-mcp-server-linux/tmux.
The reason for using a custom TMUX_TMPDIR location instead of the default /tmp/tmux-$(id -u) is to make it shareable between the Docker host and the container with correct file ownership.
and ask to Run the transcribe tool provided by the stt-mcp-server-linux MCP server.
Press the Right Ctrl key to activate Push-to-Talk functionality.
Release the key to perform the transcription and inject the resulting text into Claude.
> [!NOTE]
> Give the MCP server some time to initialize.
> You may need to explicitly verify its status with the /mcp command.
>
> Use docker logs stt-mcp-server-linux to check the progress.
>
> Once a {... "message": "Waiting for Right Ctrl key press on ... keyboard ..."} log line appears the transcription feature should be available.
>
> The transcribe tool returns immediately and runs in the background.
> Claude Code's terminal remains responsive for your input and commands while keyboard monitoring continues.
>
> To stop the transcription service, use /quit or close Claude Code.
Standalone mode (without MCP)
The speech-to-text transcription can be performed without the MCP protocol.
7. Start a new Tmux session. The example here starts a session for bash: