项目简介

'stt-mcp-server-linux' 是一个专为Linux环境设计的本地语音转文本 (Speech-to-Text, STT) MCP服务器。它利用强大的Whisper（默认）或Vosk模型进行语音识别，并通过MCP协议向大型语言模型（LLM）客户端（如Claude Code）提供“转录”工具。其核心功能是实现“按键说话”的交互模式，用户按住指定按键（默认为右Ctrl）说话，松开后语音即被转录成文本并自动注入到LLM客户端的输入框中，极大地提升了与LLM的交互效率。

主要功能点

MCP协议支持: 完全遵循MCP协议，作为服务器提供上下文信息和工具服务。
语音转文本: 集成Whisper（默认）或Vosk模型，提供高性能的语音识别能力。
按键说话 (Push-to-Talk): 通过监控键盘事件（默认为右Ctrl键）实现直观的录音控制。
LLM输入注入: 将转录后的文本直接注入到LLM客户端（如Tmux会话中的Claude Code）的输入流，无需手动复制粘贴。
Linux专属: 利用 '/dev/input' 和 '/dev/snd' 等Linux设备，确保与系统底层硬件的高效交互。

安装步骤

安装Claude Code: 参照Claude官方文档安装LLM客户端。
安装Docker Engine: 参照Docker官方文档安装Docker。
安装Tmux: 参照Tmux GitHub安装Tmux。如果您不熟悉Tmux，可以查看YouTube教程和备忘单。

克隆仓库:

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

构建Docker镜像:

bash scripts/build_docker_image.sh

下载Whisper模型:

bash scripts/download_whisper_model.sh

配置Tmux: 将以下内容添加到您的 '~/.tmux.conf' 文件中：

# 启用鼠标支持滚动
set -g mouse on

# 设置大的回滚缓冲区
set -g history-limit 1000000

# 隐藏状态栏以减少闪烁
set -g status off

# 减少Esc键延迟以减少闪烁
set -g escape-time 0

服务器配置 (用于MCP客户端)

您需要将此MCP服务器的配置信息添加到您的MCP客户端（例如Claude Code）中。以下是客户端可能需要的JSON格式配置示例，通常通过客户端的配置文件或特定命令工具进行设置。

[
    {
        "name": "stt-mcp-server-linux",
        "command": "docker",
        "args": [
            "run",
            "--rm",
            "-it",
            "--privileged",
            "-v",
            "~/.tmux:/root/.tmux",
            "-v",
            "~/.whisper:/root/.whisper",
            "-v",
            "/dev/input:/dev/input",
            "-v",
            "/dev/snd:/dev/snd",
            "stt-mcp-server-linux",
            "--output",
            "tmux",
            "--session",
            "claude",
            "--model",
            "whisper"
        ],
        "description": "本地语音转文本MCP服务器，用于将语音转录结果注入到Claude的输入流。需要访问主机/dev/input和/dev/snd设备。",
        "environment": {
            "TMUX_TMPDIR": "~/.tmux"
        }
    }
]

参数注释:

'name': MCP服务器的名称，用于在客户端中识别。
'command': 启动MCP服务器进程的可执行命令，这里是 'docker'。
'args': 传递给 'command' 的参数列表，用于启动Docker容器。
- '--rm': 容器退出时自动删除。
- '-it': 以交互模式运行并分配一个伪TTY。
- '--privileged': 授予容器特权，以便访问主机设备（如键盘和声卡）。
- '-v ~/.tmux:/root/.tmux': 挂载主机的 '~/.tmux' 目录到容器，用于Tmux会话共享。
- '-v ~/.whisper:/root/.whisper': 挂载主机的 '~/.whisper' 目录到容器，存放Whisper模型。
- '-v /dev/input:/dev/input': 挂载主机键盘输入设备，用于按键检测。
- '-v /dev/snd:/dev/snd': 挂载主机音频设备，用于录音。
- 'stt-mcp-server-linux': Docker镜像的名称。
- '--output tmux': 设置转录文本的输出方式为Tmux。
- '--session claude': 指定将文本注入到的Tmux会话名称，默认为 'claude'。
- '--model whisper': 指定使用的语音转文本模型，这里是 'whisper' (可选 'vosk')。
'description': MCP服务器的简要说明。
'environment': 传递给容器的环境变量，'TMUX_TMPDIR' 用于确保主机和容器之间Tmux会话文件的正确共享。

您可以通过以下命令将服务器添加到Claude Code客户端（假设您位于Claude项目目录中）：

bash "$STT_MCP_SERVER_LINUX_PATH"/scripts/add_mcp_server_to_claude.sh

并通过以下命令验证连接：

claude mcp list --debug

如果连接成功，您会看到类似 'stt-mcp-server-linux: ... ✓ Connected' 的输出。

基本使用方法

在一个Claude工作目录中，使用自定义的Tmux临时目录启动Claude会话：

TMUX_TMPDIR=~/.tmux tmux new-session -s claude 'claude'

在Claude界面中，输入并请求运行转录工具，例如：“Run the transcribe tool provided by the stt-mcp-server-linux MCP server”。
当服务器准备就绪（您可以通过 'docker logs stt-mcp-server-linux' 命令查看Docker容器日志，直到出现 '{... "message": "Waiting for Right Ctrl key press on ... keyboard ..."}' 提示），按下 'Right Ctrl' 键开始说话，松开 'Right Ctrl' 键结束录音。
转录后的文本将自动注入到Claude的输入框中。您可以在Claude中按 'esc' 中断当前操作，转录工具将在后台继续运行。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (用于MCP客户端)

基本使用方法

信息