SpeechWeave README

@speechweave/mcp

Official Model Context Protocol server for SpeechWeave. Use to transcribe local files and URLs from Cursor, Claude Desktop, Claude Code, Windsurf, and other MCP clients.

SpeechWeave handles short clips and long-form audio without client-side chunking. This MCP server exposes both sync tools (the transcript comes back in the same tool call) and async tools (start a job, then poll for status).

Docs: speechweave.com/docs/mcp · API reference

Install / run

Requires Node.js 18+ and a SpeechWeave API key (sk_live_…).

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

Cursor / Claude Desktop

Add to your MCP config (e.g. .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

Tools

Delivery (sync or async) is separate from service_mode (standard or deferred). Either service mode works with either delivery.

Never pass raw audio bytes over MCP. Use absolute file paths (local clients) or HTTPS URLs.

Configuration & Arguments

All transcription and job-start tools accept the following optional arguments:

• model: Choose core (default) or max.
• service_mode: Choose standard (default) or deferred (lower cost, lower priority).
• language: Optional ISO language code to force language detection.
• task: Choose transcribe (default) or translate to produce an English translation instead. language is ignored when translating.
• prompt: Optional custom vocabulary hint (proper nouns, acronyms, product names) for the first ~30s of audio.

Formatted transcripts: transcribe_file, transcribe_url, and get_job_status also accept an optional response_format (text, srt, vtt, or verbose_json) to return the transcript in that shape instead of the default plain text.

Saving to a file: transcribe_file, transcribe_url, and get_job_status accept output_file (an absolute path). The transcript is written there instead of being returned, so long transcripts stay out of the conversation. The result includes output_file and bytes_written. The path must end in .txt, .md, .json, .srt, or .vtt and cannot be inside a hidden folder. The parent folder must exist, and an existing file is only replaced when overwrite is true. With response_format: "verbose_json" the file holds the text plus segment timings as JSON.

Billing errors: a 402 comes back as a tool error with code and a hint. USER_SPEND_CAP_REACHED (raise your spend cap), PLATFORM_SPEND_CAP_REACHED (monthly account limit, request an increase), and INSUFFICIENT_BALANCE or WALLET_EMPTY (top up) all need a change on the account first, so the hint tells the assistant not to retry.

Timeout behavior: Sync tools accept an optional timeout_ms. If the transcription exceeds the timeout, the tool gracefully returns a job_id and instructs the client to switch to get_job_status polling.

Account limits and docs

• get_limits: Returns GET /v1/limits for the calling key, with MB equivalents. Use before uploading large local files.
• fetch_doc: Returns public documentation. Slug list shows the catalog. Bundled pages include quickstart, mcp, models, billing, and data_retention. Slug api fetches a live OpenAPI overview, and api/<operation_slug> returns one endpoint (e.g. api/get_v1_limits).

Example Prompts

After adding the server and restarting your client, try asking your AI assistant:

Short clip (sync)

"Use SpeechWeave to transcribe /Users/me/recordings/standup.mp3 and summarize action items."

The assistant will call transcribe_file with the absolute path and summarize the returned transcript.

Long podcast (async)

"Start a SpeechWeave job for https://cdn.example.com/three_hour_podcast.mp3, then check back until it completes."

The assistant will call start_job_url, then periodically call get_job_status until the status reaches completed.

Translate to subtitles (sync)

"Translate /Users/me/recordings/spanish_interview.mp3 into English SRT subtitles using SpeechWeave."

The assistant will call transcribe_file with task: "translate" and response_format: "srt".