mcp-asr

mcp-asr 是一个 stdio MCP 语音转写服务，用于调用可配置的 OpenAI-compatible transcription 接口：

Claude / Codex / Agent → stdio MCP → OpenAI-compatible transcription URL

可以通过 PyPI 安装 Python MCP Server，也可以通过 npx 自动准备并启动固定 版本的 PyPI 包。

公共配置

URL 和模型的优先级为：启动参数 > 环境变量。

文件是否可访问由宿主沙箱、操作系统权限和 MCP 客户端的用户授权决定；mcp-asr 本身不额外弹出文件授权确认。

通过 PyPI 使用

安装

python3 -m venv .venv
.venv/bin/pip install mcp-asr

安装后可以使用：

.venv/bin/mcp-asr
.venv/bin/python3 -m mcp_asr

手工运行

MCP_ASR_TOKEN='your-token' \
.venv/bin/mcp-asr \
  --url https://api.openai.com/v1/audio/transcriptions \
  --model qwen3-asr

Claude Code

{
  "mcpServers": {
    "speech-to-text": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/mcp-asr",
      "args": [
        "--url",
        "https://api.openai.com/v1/audio/transcriptions",
        "--model",
        "qwen3-asr"
      ],
      "env": {
        "MCP_ASR_TOKEN": "your-token"
      },
      "timeout": 240000
    }
  }
}

Codex

[mcp_servers.speech-to-text]
command = "/absolute/path/to/.venv/bin/mcp-asr"
args = [
  "--url", "https://api.openai.com/v1/audio/transcriptions",
  "--model", "qwen3-asr",
]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 240

[mcp_servers.speech-to-text.env]
MCP_ASR_TOKEN = "your-token"

通过 npx 使用

npm 包是 PyPI mcp-asr==0.1.3 的薄启动器。首次运行会在用户缓存目录创建 Python 虚拟环境并安装固定版本的 PyPI 包。

前置条件

• Node.js 18 或更高版本；
• Python 3.10 或更高版本；
• 首次准备时可以访问 PyPI。

首次预热

建议在注册 MCP 前完成环境准备，避免首次启动超过 MCP startup timeout：

npx -y mcp-asr@0.1.3 --prepare

如需指定 Python：

MCP_ASR_PYTHON=/path/to/python3 \
npx -y mcp-asr@0.1.3 --prepare

手工运行

MCP_ASR_TOKEN='your-token' \
npx -y mcp-asr@0.1.3 \
  --url https://api.openai.com/v1/audio/transcriptions \
  --model qwen3-asr

也可以通过环境变量提供 URL 和模型：

MCP_ASR_TOKEN='your-token' \
MCP_ASR_URL='https://api.openai.com/v1/audio/transcriptions' \
MCP_ASR_MODEL='qwen3-asr' \
npx -y mcp-asr@0.1.3

Claude Code

{
  "mcpServers": {
    "speech-to-text": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-asr@0.1.3",
        "--url",
        "https://api.openai.com/v1/audio/transcriptions",
        "--model",
        "qwen3-asr"
      ],
      "env": {
        "MCP_ASR_TOKEN": "your-token"
      },
      "timeout": 240000
    }
  }
}

Codex

[mcp_servers.speech-to-text]
command = "npx"
args = [
  "-y",
  "mcp-asr@0.1.3",
  "--url", "https://api.openai.com/v1/audio/transcriptions",
  "--model", "qwen3-asr",
]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 240

[mcp_servers.speech-to-text.env]
MCP_ASR_TOKEN = "your-token"

opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "speech-to-text-local": {
      "type": "local",
      "command": ["npx",
        "-y",
        "mcp-asr@0.1.3",
        "--url",
        "https://api.openai.com/v1/audio/transcriptions",
        "--model",
        "qwen3-asr"
        ],
      "enabled": true,
      "timeout": 120000,
      "environment": {
        "MCP_ASR_TOKEN": "your-token"
        }
    }
  }
}

npx 可选环境变量

默认缓存目录：

• macOS：~/Library/Caches/mcp-asr-npx/
• Linux：${XDG_CACHE_HOME:-~/.cache}/mcp-asr-npx/

标准 pip 环境变量，例如 PIP_INDEX_URL、PIP_EXTRA_INDEX_URL、代理和证书 变量，也会传递给安装进程。

transcribe_audio

使用限制：

• file_path 可以指向 MCP Server 进程有权限访问的任意本地音频；
• 选择并授权文件由用户和 MCP 客户端负责；
• 最大音频大小为 25 MB；
• 支持 flac、mp3、mp4、mpeg、mpga、m4a、ogg、opus、 aac、wav、webm；
• MCP 工具调用不能覆盖启动时配置的 URL 和模型。