# SpeechWeave [Health: Active]

**Category:** 🎙️ Speech-to-Text  
**Repository:** https://github.com/speechweave/speechweave-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 817  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/speechweave

## Description
Transcribe local files and URLs with SpeechWeave's OpenAI-compatible API.

## Tools
Capabilities this server exposes over MCP:

- **transcribe_file** — 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). Set task='translate' to get an English translation instead of a same-language transcript. On wait timeout, returns job_id, then call get_job_status. For long audio you plan to poll yourself, use start_job_file instead.
- **transcribe_url** — 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. Set task='translate' to get an English translation instead of a same-language transcript. On wait timeout, returns job_id, then call get_job_status. For long audio you plan to poll yourself, use start_job_url instead.
- **start_job_file** — 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. Set task='translate' for an English translation instead of a same-language transcript.
- **start_job_url** — 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. Set task='translate' for an English translation instead of a same-language transcript.
- **get_job_status** — Fetch the current status of a transcription job (and transcript when completed). Poll until status is completed, failed, or cancelled. Pass response_format ('srt', 'vtt', or 'verbose_json') on a completed job to fetch it re-formatted.
- **cancel_job** — Cancel a queued or processing transcription job. Fails if the job is already terminal.
- **get_limits** — Fetch upload size ceilings for the calling API key (GET /v1/limits). Returns max_input_bytes, sync_max_bytes, and proxy_max_bytes plus MB equivalents. Call before transcribe_file or start_job_file when file size is large.
- **fetch_doc** — Return public SpeechWeave documentation for a slug. Use slug 'list' for the catalog. Bundled pages include quickstart, mcp, models, billing, and data_retention. Use slug 'api' for a live OpenAPI overview, or 'api/<operation_slug>' for one endpoint (e.g. api/get_v1_limits).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "speechweave": {
    "command": "npx",
    "args": ["-y","@speechweave/mcp"]
  }
}
```

## Documentation & README

# @speechweave/mcp

[![npm version](https://img.shields.io/npm/v/@speechweave/mcp.svg)](https://www.npmjs.com/package/@speechweave/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official [Model Context Protocol](https://modelcontextprotocol.io) server for [SpeechWeave](https://speechweave.com). 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](https://speechweave.com/docs/mcp) · [API reference](https://speechweave.com/docs/api)

## Install / run

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

```bash
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`):

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

## Claude Code

```bash
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"`.*