@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 wait-first tools (get a transcript in one turn) and async create + poll tools (start a job, then check 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_..."
			}
		}
	}
}

Tools

Tool	Mode	When to use
transcribe_file	Wait-first	Absolute local path; wait until transcript is ready
transcribe_url	Wait-first	Public HTTPS URL; wait until transcript is ready
start_job_file	Async	Absolute local path; return job_id immediately
start_job_url	Async	Public HTTPS URL; return job_id immediately
get_job_status	Poll	Fetch status / transcript for a job id
cancel_job	Control	Cancel a queued or processing job
get_limits	Info	Upload size ceilings for your API key
fetch_doc	Info	Public docs by slug (bundled pages + live OpenAPI)

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 for the background queue. synchronous is accepted as an alias for standard.
• 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.

Timeout behavior: Wait-first 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; 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 (wait-first)

"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 + poll)

"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 (wait-first)

"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".