SpeechWeave

@speechweave/mcp

SpeechWeave 的官方 Model Context Protocol 服务。可在 Cursor、Claude Desktop、Claude Code、Windsurf 和其他 MCP 客户端中转录本地文件和 URL。

SpeechWeave 可处理短片段和长音频，无需在客户端分块。此 MCP 服务提供同步工具（转录文本会在同一次工具调用中返回）和异步工具（启动任务后轮询状态）。

文档：speechweave.com/docs/mcp · API 参考

安装 / 运行

需要 Node.js 18+ 和 SpeechWeave API 密钥（sk_live_…）。

export SPEECHWEAVE_API_KEY="sk_live_..."
npx -y @speechweave/mcp

Cursor / Claude Desktop

添加到 MCP 配置（例如 .cursor/mcp.json、claude_desktop_config.json）：

{
	"mcpServers": {
		"speechweave": {
			"command": "npx",
			"args": ["-y", "@speechweave/mcp"],
			"env": {
				"SPEECHWEAVE_API_KEY": "sk_live_..."
			}
		}
	}
}

Claude Code

claude mcp add speechweave --env SPEECHWEAVE_API_KEY=sk_live_... -- npx -y @speechweave/mcp

工具

工具	交付方式	适用场景
transcribe_file	同步	绝对本地路径。在此次调用中返回转录文本
transcribe_url	同步	公共 HTTPS URL。在此次调用中返回转录文本
start_job_file	异步	绝对本地路径。立即返回 job_id
start_job_url	异步	公共 HTTPS URL。立即返回 job_id
get_job_status	异步	轮询任务状态 / 转录文本
cancel_job	不适用	取消排队中或处理中的任务
get_limits	不适用	API 密钥的上传大小上限
fetch_doc	不适用	按 slug 获取公开文档（打包页面 + 实时 OpenAPI）

交付方式（同步或异步）与 service_mode（standard 或 deferred）彼此独立。任一种服务模式都可搭配任一种交付方式。

**切勿通过 MCP 传递原始音频字节。**请使用绝对文件路径（本地客户端）或 HTTPS URL。

配置与参数

所有转录和启动任务的工具都接受以下可选参数：

• model：选择 core（默认）或 max。
• service_mode：选择 standard（默认）或 deferred（成本更低，优先级也更低）。
• language：可选的 ISO 语言代码，用于指定语言检测。
• task：选择 transcribe（默认）或 translate，以生成英文译文。翻译时会忽略 language。
• prompt：可选的自定义词汇提示（专有名词、缩略词、产品名称），适用于音频最初约 30 秒。

格式化转录文本：transcribe_file、transcribe_url 和 get_job_status 也接受可选的 response_format（text、srt、vtt 或 verbose_json），以指定格式返回转录文本，而非默认的纯文本。

保存到文件：transcribe_file、transcribe_url 和 get_job_status 接受 output_file（绝对路径）。转录文本会写入该路径，而不是直接返回，从而避免长篇转录文本占用对话空间。结果包含 output_file 和 bytes_written。路径必须以 .txt、.md、.json、.srt 或 .vtt 结尾，且不能位于隐藏文件夹中。父文件夹必须已存在；只有当 overwrite 为 true 时才会替换现有文件。使用 response_format: "verbose_json" 时，文件中会以 JSON 格式保存文本和片段时间戳。

**账单错误：**402 错误会作为工具错误返回，其中包含 code 和 hint。USER_SPEND_CAP_REACHED（提高支出上限）、PLATFORM_SPEND_CAP_REACHED（账户月度限额，请求提高限额）以及 INSUFFICIENT_BALANCE 或 WALLET_EMPTY（充值）都需要先更改账户设置，因此提示会告知助手不要重试。

**超时行为：**同步工具接受可选的 timeout_ms。如果转录超时，工具会妥善返回 job_id，并指示客户端改用 get_job_status 轮询。

账户限制和文档

• get_limits：返回当前调用密钥对应的 GET /v1/limits，并提供 MB 等效值。上传较大的本地文件前，请先使用此工具。
• fetch_doc：返回公开文档。使用 slug list 可查看目录。内置页面包括 quickstart、mcp、models、billing 和 data_retention。使用 slug api 可获取实时 OpenAPI 概览，使用 api/<operation_slug> 可获取单个端点（例如 api/get_v1_limits）。

示例提示词

添加服务并重启客户端后，可以尝试向 AI 助手提出以下请求：

短片段（同步）

“使用 SpeechWeave 转录 /Users/me/recordings/standup.mp3，并总结待办事项。”

助手会使用绝对路径调用 transcribe_file，并总结返回的 transcript。

长播客（异步）

“为 https://cdn.example.com/three_hour_podcast.mp3 启动一个 SpeechWeave 任务，然后持续查询，直到任务完成。”

助手会调用 start_job_url，然后定期调用 get_job_status，直到状态变为 completed。

翻译成字幕（同步）

“使用 SpeechWeave 将 /Users/me/recordings/spanish_interview.mp3 翻译成英文 SRT 字幕。”

助手会使用 task: "translate" 和 response_format: "srt" 调用 transcribe_file。