Co-Authored-By: Claude

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:

   git clone https://github.com/marcindulak/stt-mcp-server-linux
   cd stt-mcp-server-linux
   export STT_MCP_SERVER_LINUX_PATH=$(pwd)
   

4. Build the Docker image of the MCP server:

   bash scripts/build_docker_image.sh
   

5. Download the Whisper tiny model under ~/.stt-mcp-server-linux/whisper:

   bash scripts/download_whisper_model.sh
   

6. Configure Tmux, so ~/.tmux.conf contains at least:

   # Enable mouse support for scrolling
   set -g mouse on
   
   # Set large scrollback lines buffer
   set -g history-limit 1000000
   
   # Hide status bar to reduce flicker
   set -g status off
   
   # Reduce escape key delay to reduce flicker
   set -g escape-time 0
   

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.

   bash "${STT_MCP_SERVER_LINUX_PATH}/scripts/add_mcp_server_to_claude.sh"
   

   Verify the Claude connection to the MCP server with:

   claude mcp list
   

   Expected output:

   stt-mcp-server-linux: ... ✓ Connected
   

[!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.

   TMUX_TMPDIR=~/.stt-mcp-server-linux/tmux tmux new-session -s claude 'claude'
   

   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

... View full README on GitHub