@speechweave/mcp
OfficialTranscribes local audio/video files and public HTTPS URLs via SpeechWeave, either synchronously (wait for the transcript) or asynchronously (start a job and poll/cancel it).
Transcribe synchronously with
transcribe_file(absolute local path) ortranscribe_url(public HTTPS URL) — returns the transcript in the same call, or ajob_idiftimeout_ms(default 1 hour) is exceeded.Start async jobs with
start_job_file/start_job_url— returns ajob_idimmediately for long media, then poll withget_job_statusuntilcompleted,failed, orcancelled.Cancel jobs with
cancel_job(queued or processing; fails on terminal jobs).Choose a model tier:
core(default) ormaxfor hardest audio.Force a language with a 2-letter ISO code (e.g.
en,es).Pick a service mode:
deferred(default, background queue for long audio) orsynchronous(higher priority, smaller size cap).Handle long work: sync tools degrade gracefully into a
job_idon timeout, so you can switch to polling.Constraints: never pass raw audio bytes over MCP — only absolute filesystem paths or publicly reachable HTTPS URLs; relative paths are rejected.
Note: this schema exposes only 6 tools. README-documented features (get_limits, fetch_doc, task: translate, prompt, response_format, output_file/overwrite, and the standard service mode) are not present here, and service_mode defaults to deferred rather than standard.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@speechweave/mcp Transcribe /Users/me/recordings/standup.mp3"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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/mcpRelated MCP server: whisper-transcribe-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/mcpTools
Tool | Delivery | When to use |
| sync | Absolute local path. Returns the transcript in this call |
| sync | Public HTTPS URL. Returns the transcript in this call |
| async | Absolute local path. Returns |
| async | Public HTTPS URL. Returns |
| async | Poll status / transcript for a job id |
| n/a | Cancel a queued or processing job |
| n/a | Upload size ceilings for your API key |
| n/a | Public docs by slug (bundled pages + live OpenAPI) |
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: Choosecore(default) ormax.service_mode: Choosestandard(default) ordeferred(lower cost, lower priority).language: Optional ISO language code to force language detection.task: Choosetranscribe(default) ortranslateto produce an English translation instead.languageis 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: ReturnsGET /v1/limitsfor the calling key, with MB equivalents. Use before uploading large local files.fetch_doc: Returns public documentation. Sluglistshows the catalog. Bundled pages includequickstart,mcp,models,billing, anddata_retention. Slugapifetches a live OpenAPI overview, andapi/<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.mp3and 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.mp3into English SRT subtitles using SpeechWeave."
The assistant will call transcribe_file with task: "translate" and response_format: "srt".
Available Tools
6 toolscancel_jobCancel jobA
Cancel a queued or processing transcription job. Fails if the job is already terminal.
Inputs: job_id (required).
get_job_statusGet job statusA
Fetch the current status of a transcription job (and transcript when completed). Poll until status is completed, failed, or cancelled.
Inputs: job_id (required).
start_job_fileStart job from local file (async)A
Upload a local audio/video file and return a job id immediately without waiting. Use for long recordings or when you will poll later with get_job_status. Pass an absolute filesystem path.
Inputs: path (required), model, language, service_mode.
start_job_urlStart job from URL (async)A
Create a transcription job from a public HTTPS URL and return a job id immediately. Use for long media or deferred workflows; poll with get_job_status until completed, failed, or cancelled.
Inputs: url (required), model, language, service_mode.
transcribe_fileTranscribe local file (wait)A
Upload a local audio/video file and wait until transcription finishes. Prefer for short/medium clips when you need the transcript in this turn. Pass an absolute filesystem path (never raw binary). On wait timeout, returns job_id — then call get_job_status. For long audio you plan to poll yourself, use start_job_file instead.
Inputs: path (required), model, language, timeout_ms, +1 more.
transcribe_urlTranscribe URL (wait)A
Start transcription from a public HTTPS URL and wait until it finishes. Prefer for short/medium media when you need the transcript in this turn. On wait timeout, returns job_id — then call get_job_status. For long audio you plan to poll yourself, use start_job_url instead.
Inputs: url (required), model, language, timeout_ms, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clear, distinct role: synchronous vs. asynchronous, file vs. URL, status polling, and cancellation. No ambiguity between any pair.
All tools follow a consistent verb_noun pattern with underscores (e.g., transcribe_file, start_job_url, get_job_status). No mixing of conventions.
With 6 tools covering synchronous and asynchronous transcription from both files and URLs, plus status and cancellation, the count is well-scoped for the domain without redundancy.
Covers all essential operations: create jobs (sync/async, file/URL), check status, cancel. Missing a list-all-jobs endpoint, but core transcription workflow is complete.
Maintenance
Related MCP Connectors
MCP server for RiverScript, an AI transcription platform - fetches transcripts shared via a link.
MCP server for Speech-to-Text
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for offline speech-to-text and speaker diarization, enabling AI agents to transcribe audio locally without cloud APIs.43 PyPI4MIT
- AlicenseAqualityBmaintenanceMCP server for audio transcription using local faster-whisper or OpenAI Whisper API, enabling multilingual transcription with optional GPT post-processing.3180 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceMCP server for audio transcription with speaker diarization. Transcribes MP3/WAV files using Faster-Whisper and pyannote.audio, outputs markdown with speaker labels, timestamps, summaries, and action items.1MIT
- AlicenseAqualityDmaintenanceLocal, private audio transcription MCP server enabling AI agents to transcribe audio files entirely on-device without uploading data.3MIT