OpenTranscribe MCP

OpenTranscribe MCP

掌控录音设备，自主选择智能服务。

OpenTranscribe 是一款开源 MCP 服务，可将音频发送到你选择的语音转文本模型，并返回统一的、与服务提供商无关的转录文本格式。

它秉持一个简单的理念：购买一台出色的录音设备，不应让你受限于某一家转录服务的订阅。使用 Plaud、手机、开源穿戴设备或任何你获准访问的其他音频来源，然后选择 Microsoft MAI、ElevenLabs Scribe 或 Groq Whisper，无需更改下游工作流。

OpenTranscribe 不会破解硬件或绕过访问控制。它只处理操作人员获准访问的音频。

工作原理

OpenTranscribe 保持集成边界稳定：录音设备提供音频文件或 HTTPS URL，服务选择或调用所请求的语音转文本服务提供商，下游工具则接收相同的标准化转录文本格式。

v1 版本包含的内容

• 在 /mcp 提供 MCP Streamable HTTP，支持无状态运行以及 bearer 或外部 OIDC 身份验证
• transcribe_audio、list_transcription_models、estimate_transcription_cost、get_transcript_chunk 和 delete_transcript
• Microsoft MAI-Transcribe-2、ElevenLabs scribe-v2 和 Groq Whisper 适配器
• 明确的能力协商、路由策略、重试和可观测的回退机制
• 在支持时透传 HTTPS URL，否则使用有界流式代理
• SSRF 防护、签名 URL 脱敏、不记录内容日志，以及成本和资源限制
• 默认禁用保留；可选使用内存或兼容 S3 的临时结果存储
• Docker、面向生产环境的 Scaleway Serverless Containers Terraform、测试和 GitHub Actions CI

Linux 桌面版

可选的 Debian 软件包 OpenTranscribe Setup 集成了 Python 运行时、引擎和原生设置应用。安装软件包、添加服务提供商密钥并连接本地 MCP 客户端即可——无需 Python、无需 uv，也无需配置文件。随后，引擎会作为由客户端拥有的单一 STDIO 进程运行，不会打开网络套接字。

它不会影响下方的托管服务和命令行使用方式。请参阅 Linux 上的 OpenTranscribe Setup；其发布验收记录见 docs/desktop-acceptance.md，其中每个场景的初始状态均为尚未测试。

十分钟快速入门

要求：Python 3.12 和 uv，或 Docker。

git clone https://github.com/fbossiere/open-transcribe-mcp.git
cd open-transcribe-mcp

创建一个私有的 .env 文件，其中只包含所选提供方的设置和一个强随机 MCP bearer token。Microsoft 的配置如下：

OT_ENVIRONMENT=prod
OT_HOST=127.0.0.1
OT_DEFAULT_PROVIDER=microsoft
OT_DEFAULT_MODEL=MAI-Transcribe-2
OT_MICROSOFT__ENDPOINT=https://YOUR-RESOURCE.cognitiveservices.azure.com
OT_MICROSOFT__API_KEY=YOUR-KEY
OT_SECURITY__AUTH_MODE=bearer
OT_SECURITY__BEARER_TOKEN=YOUR-RANDOM-TOKEN

使用其他服务时，请采用完整的 Groq、ElevenLabs 或多提供方配置方案。对于未使用的设置，请直接省略，不要在 .env.example 中保留空 URL 或数字；该文件仅供查看配置项。使用 chmod 600 .env 保护此文件。

启动服务：

uv sync
uv run open-transcribe-mcp

MCP 端点为 http://localhost:8000/mcp；/healthz 和 /readyz 提供探测接口。

通过已连接的提供方，运行附带的双语双人合成录音：

uv run python examples/transcribe.py --token YOUR-RANDOM-TOKEN

测试素材和参考转录文本不含敏感信息，且可再分发。若要使用自己的音源，可将另一个经授权的公开 HTTPS 音频 URL 作为第一个参数传入。

连接 FastMCP 客户端：

import asyncio
from fastmcp import Client


async def main() -> None:
    async with Client("http://localhost:8000/mcp", auth="YOUR-RANDOM-TOKEN") as client:
        models = await client.call_tool("list_transcription_models", {})
        print(models)
        result = await client.call_tool(
            "transcribe_audio",
            {
                "request": {
                    "source": {"type": "url", "url": "https://example.org/authorized-audio.mp3"},
                    "provider": "auto",
                    "routing_policy": "quality",
                }
            },
        )
        print(result)


asyncio.run(main())

选择提供方不会改变响应约定。设置 provider 和 model 可显式切换；也可以使用 auto，并选择 default、quality、cost 或 latency 路由。

上面有意未设置 diarization、timestamps 和 transcript_style：未设置的功能不会被请求，因此请求会路由到任意已配置的模型，响应元数据则会报告该模型实际应用的功能。指定其中一项就会将其设为要求——例如，"diarization": True 会排除所有无法区分说话者的模型，而不会静默返回单人转录文本。请参阅提供方与功能。

Docker

使用已发布的映像和快速入门中的私有环境文件：

docker run --rm --env-file .env \
  -e OT_ENVIRONMENT=prod -e OT_HOST=0.0.0.0 \
  -p 127.0.0.1:8000:8000 \
  ghcr.io/fbossiere/open-transcribe-mcp:1.2.2

此配置会将主机端口绑定到本机；若要远程托管，请在前面配置 HTTPS 代理。你也可以使用 docker build -t open-transcribe-mcp:1.2.2 . 从源代码构建。请在运行时注入提供方凭据。该映像包含 s3 扩展，但除非进行配置，否则结果存储仍处于禁用状态。

在 Scaleway 上部署

参考模块 infra/scaleway 会配置私有映像注册表、支持缩容至零（0–3 个实例）的无服务器容器、HTTPS 入站流量和健康探测。你也可以选择添加带 TTL 的结果存储桶和运行时身份。

1. 创建专用的 Scaleway Project 和部署 API 密钥，并授予文档所述的 IAM 权限。 将 SCW_ACCESS_KEY 和 SCW_SECRET_KEY 提供给部署 shell。

2. 将 infra/scaleway/terraform.tfvars.example 复制到该目录下的 terraform.tfvars。 填入项目 ID、提供方密钥、身份验证设置，并设置 image_tag = "1.2.2"。 模板配置了 ElevenLabs 和 Groq；使用前请检查 ElevenLabs 的数据保留选项。

3. 初始化注册表，将公开发布映像复制到其中，然后检查并应用完整部署。在 infra/scaleway 目录中：

   terraform init
   terraform apply -target=scaleway_registry_namespace.this
   IMAGE_REFERENCE="$(terraform output -raw image_reference)"
   REGISTRY_ENDPOINT="$(terraform output -raw registry_endpoint)"
   printf '%s' "$SCW_SECRET_KEY" | docker login "${REGISTRY_ENDPOINT%%/*}" \
     --username nologin --password-stdin
   docker buildx imagetools create --tag "$IMAGE_REFERENCE" \
     ghcr.io/fbossiere/open-transcribe-mcp:1.2.2
   terraform plan -out=open-transcribe.tfplan
   terraform apply open-transcribe.tfplan
   terraform output -raw mcp_endpoint
   

4. 检查 /healthz、/readyz、MCP 身份验证，以及一次简短且经过授权的转录。 Scaleway 完整指南涵盖发布摘要验证、接管现有部署、OIDC 设置、升级、回滚和结果存储权限。

初始化阶段的 apply 操作用于新建基础设施。若要保留现有注册表、命名空间和容器的 ID 及端点，请先将其导入状态。请妥善保管真实的 terraform.tfvars、状态文件和保存的计划：即使输出已隐藏，状态文件和计划中仍可能包含机密。发布新版本不会自动更新 Scaleway 部署。

配置和服务组合

可分别选择服务提供方、MCP 身份验证和结果存储。服务提供方密钥保留在服务器上，绝不会作为工具参数接受。完整的环境变量/Terraform 示例、设置优先级、密钥权限和故障排除说明，请参阅配置指南。

转录服务	配置	用途和限制
仅 Microsoft	Microsoft endpoint + key；默认值为 microsoft / MAI-Transcribe-2	支持说话人分离和清晰/逐字输出
仅 ElevenLabs	ElevenLabs key；默认值为 elevenlabs / scribe-v2	支持说话人分离；选择符合条件的零保留模式，或明确接受标准模式
仅 Groq	Groq key；默认值为 groq / Whisper 模型	逐字转录；不支持说话人分离
多个服务提供方	各服务提供方的凭据；一组匹配的默认值	请求可选择任何已配置的服务提供方；排序前会检查兼容性

OT_DEFAULT_PROVIDER 和 OT_DEFAULT_MODEL 是偏好设置，不是服务提供方允许列表。显式请求可以选择其他已配置的模型。托管请求默认允许临时回退；如果音频必须只发送给一个服务提供方，请使用 allow_fallback=false。若要强制要求法语说话人轮次，请使用 language=fr、diarization=true 和 strict_capabilities=true；请参阅 Scribe 配方。Groq 无法满足此要求，因此会被拒绝，而不会悄然返回未经说话人分离的转录结果。

身份验证 / 存储	必需配置	组合规则
HTTP bearer	MCP token；Terraform auth_mode = "bearer"	适用于任何服务提供方；token 与服务提供方密钥分开
HTTP OIDC	Issuer、JWKS、service origin、scope 和 entitlement；auth_mode = "oidc"	适用于任何服务提供方；使用 Keycloak 等外部身份提供方
托管桌面 STDIO	Setup TOML 和 Secret Service keyring	本地进程身份验证；在 Setup 中启用服务提供方并设置隐私权限
不存储结果	默认值为 disabled；Terraform enable_result_store = false	内联输出；需要存储或自动处理的结果超出大小限制时会明确失败
临时 S3 结果	Cursor secret；Terraform enable_result_store = true	在多个实例间共享分块，支持 TTL 和删除；需要额外的 IAM 权限
内存结果	OT_RESULT_STORE__BACKEND=memory + cursor secret	仅用于本地/测试；不适用于 Scaleway 冷启动或多个实例

ElevenLabs 请求默认使用零保留模式，这需要符合条件的 Enterprise 账户。标准账户在接受服务提供方侧的数据保留后，必须显式设置 OT_ELEVENLABS__ZERO_RETENTION=false。禁用 OpenTranscribe 存储并不会禁用服务提供方的数据保留。请参阅配置和数据保留。

对于常规 HTTP，OT_* 环境变量会覆盖工作目录中的 .env。Terraform 会从私有 tfvars 注入非机密和机密映射，同时强制执行生产环境安全设置。托管桌面模式会忽略环境中的现有设置；仅在 keyring 中保存密钥并不会启用相应服务提供方。更改密钥或默认值需要重启或执行 Terraform apply，而不需要新的应用镜像。使用新的应用版本需要发布镜像，并单独更新部署。

发布与升级

发布协议是维护者的操作手册：语义化版本控制、版本一致性、本地检查、发布 PR、基于经过审核的 main 创建签名标签、自动发布、制品验证，以及部分失败后的恢复。

Git 标签使用 v1.2.2；Python/MCP 元数据和镜像标签使用 1.2.2。工作流会发布到 PyPI、MCP Registry、GHCR 和 Linux 软件包，然后创建包含校验和及来源信息的不可变 GitHub 发布版本。每个部署各自选择版本和配置。升级 Scaleway 时，将选定的发布版本复制到私有注册表，更新 image_tag（如果固定了版本，还要更新发布摘要），审核计划、执行应用并验证端点。

安全与隐私默认设置

• 必须使用源 HTTPS；
• 拒绝私有、环回、链路本地、多播、保留地址及元数据目的地；
• 解析并验证每个重定向目标；
• 代理下载连接到经过验证的公网 IP，同时保留 HTTPS SNI 和原始 Host 标头；
• 源下载内容会流式传输到临时文件，并限制字节数，之后删除；
• 不记录签名 URL 查询参数、音频、转录文本、授权标头和短语提示；
• 不发送项目遥测数据；
• 除非明确启用并使用结果存储，否则不会保留转录内容。
• 默认启用 ElevenLabs 零保留请求；禁用该功能是运维人员的主动选择。

在公开服务之前，请阅读 SECURITY.md、威胁模型和保留政策。

已知限制

OpenTranscribe 目前面向可自托管的单租户安装。我们有意不保证各提供商的功能完全一致；能力协商会揭示差异，而非将其隐藏。URL 导入是唯一的远程输入类型。同步提供商限制仍然适用。OIDC 支持外部身份提供商；异步任务仍是未来功能。内存存储既不持久，也不支持水平扩展。S3 查找优先考虑简单的部署契约，而非对超大型存储桶进行索引；请专门设置结果前缀并强制执行生命周期删除。

应用控制不能替代网络策略。面向互联网的运维人员仍应结合精确的源主机允许列表与出站防火墙规则。

提供商的价格、API 和功能会发生变化。仓库中包含的元数据仅供参考，并非合同报价。

桌面软件包面向 amd64 架构的 Ubuntu 24.04 LTS，目前尚不支持其他版本、桌面环境或架构。尚无 MCP 客户端完成端到端注册测试记录，因此 OpenTranscribe Setup 会将自动注册标记为未经测试，并通过读取注册信息来验证。

录音同意

OpenTranscribe 会处理运维人员提供的音频。录制和转录他人的内容可能受同意、隐私、雇佣、电信或数据保护法律约束。运维人员有责任确保拥有必要的权利并取得同意。

转录内容是不可信数据。OpenTranscribe 绝不会将其解释为指令；下游 Agent 必须维护同样的边界。

文档

规范文档站点：fbossiere.github.io/open-transcribe-mcp。

• 架构
• 配置与服务组合
• 提供商与功能
• OIDC 身份验证
• 安全模型
• 隐私与保留期限
• 在 Linux 上设置 OpenTranscribe
• 桌面版发布验收
• Scaleway 部署
• 发布协议
• 教程：在 Ubuntu 上逐步使用 Plaud (PDF)
• Plaud 使用方案
• ChatGPT + Google Drive 使用方案
• 参与贡献
• 治理
• 支持
• 完整产品与技术规范

参与贡献

欢迎贡献。请先阅读贡献指南；进行重大工作前，请先提交功能问题；漏洞仅通过 SECURITY.md 中的私密流程报告。

独立性与商标

OpenTranscribe 是一个独立的开源项目，由贡献者维护。它与 Plaud、Microsoft、ElevenLabs、Groq 或任何转录服务提供商均无关联，也未获得其认可或赞助。

Plaud 及所有提供商的产品名称均为其各自所有者的商标。

许可证

Apache License 2.0。请参阅 LICENSE。