Skip to main content
Glama
@speechweave/mcp

@speechweave/mcp

Official
by speechweave

@speechweave/mcp

npm version License: MIT

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

Related 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/mcp

Tools

Tool

Delivery

When to use

transcribe_file

sync

Absolute local path. Returns the transcript in this call

transcribe_url

sync

Public HTTPS URL. Returns the transcript in this call

start_job_file

async

Absolute local path. Returns job_id immediately

start_job_url

async

Public HTTPS URL. Returns job_id immediately

get_job_status

async

Poll status / transcript for a job id

cancel_job

n/a

Cancel a queued or processing job

get_limits

n/a

Upload size ceilings for your API key

fetch_doc

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

Available Tools

6 tools
cancel_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

    A4.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clear, distinct role: synchronous vs. asynchronous, file vs. URL, status polling, and cancellation. No ambiguity between any pair.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with underscores (e.g., transcribe_file, start_job_url, get_job_status). No mixing of conventions.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers