speechweave-mcp

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