# @voxloom/mcp

Model Context Protocol server for [Voxloom](https://voxloom.ai). Lets an
assistant transcribe a video or podcast, then read, search and summarise the
result.

Works with Claude Desktop, Claude Code, Cursor, Cline, and anything else that
speaks MCP over stdio.

## Setup

You need a Voxloom API key from **API keys** in your
[dashboard](https://voxloom.ai/dashboard). API access is included from the
Studio plan upwards.

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "voxloom": {
      "command": "npx",
      "args": ["-y", "@voxloom/mcp"],
      "env": { "VOXLOOM_API_KEY": "sk_prod_..." }
    }
  }
}
```

### Claude Code

```bash
claude mcp add voxloom --env VOXLOOM_API_KEY=sk_prod_... -- npx -y @voxloom/mcp
```

### Cursor and Cline

Both read the same shape of config as Claude Desktop. Add the `voxloom` entry
above to the MCP settings.

## Tools

| Tool | Charges | What it does |
| --- | --- | --- |
| `estimate` | No | What a recording would cost, and whether the balance covers it |
| `transcribe` | **Yes** | Transcribes a recording and returns the transcript |
| `get_transcript` | No | Reads a transcript by job id, or reports progress |
| `search_transcript` | No | Finds where something was said, with timestamps |
| `get_summary` | No | Abstract, key points, quotes and chapters |
| `list_transcripts` | No | Recent transcripts and their job ids |
| `get_speakers` | No | Who is in a transcript and for how long |
| `rename_speaker` | No | Renames a speaker everywhere, exports included |
| `cancel_transcription` | No | Stops a running job; refunds the remainder |
| `list_languages` | No | The 101 languages, and which can be translated into |

## Two things worth knowing

**Transcription costs money.** `transcribe` prices the job before submitting it
and refuses anything above a ceiling (30 standard minutes by default) unless it
is passed `confirm_spend: true`. So an assistant cannot quietly spend your
balance on a three-hour video: it has to tell you the cost and ask.

Raise or lower the ceiling with `VOXLOOM_MAX_CREDITS_PER_CALL`. 120 credits is
one standard minute.

**Transcripts are large.** Nothing returns a whole one by default. Reads are
budgeted and say plainly when they truncated, so the assistant knows it is
looking at an excerpt. For a question about one moment, `search_transcript` is
both cheaper and more accurate than reading everything.

## Configuration

| Variable | Default | What it does |
| --- | --- | --- |
| `VOXLOOM_API_KEY` | required | Your API key |
| `VOXLOOM_BASE_URL` | `https://voxloom.ai` | Override for self-hosting |
| `VOXLOOM_MAX_CREDITS_PER_CALL` | `3600` | Spend ceiling per `transcribe` call |
| `VOXLOOM_WAIT_MS` | `90000` | How long `transcribe` waits before handing back a job id |
| `VOXLOOM_MAX_CHARS` | `12000` | Text budget for a transcript read |

## Example conversation

> **You:** Transcribe https://youtu.be/VIDEO_ID and tell me what they say about
> consensus.

The assistant estimates the cost, transcribes it, then searches the transcript
for "consensus" rather than reading all 9,000 words, and answers with
timestamps you can check.

## Development

```bash
npm install
npm run typecheck
npm test        # builds, then runs the tests against dist/
```

Tests run against the compiled output rather than the sources, because that is
what ships and it means the NodeNext module specifiers resolve as they will at
runtime.

## Licence

MIT.