How do I let Claude Code transcribe audio and video?
Add the KolWrite MCP server with one claude mcp add command, or install the kolwrite-transcribe skill. Claude Code then uploads your file, starts the job, waits and writes the transcript, subtitles or translation into your project, billed per second to your KolWrite credits.
What you do once
Create the account and the key yourself at console.kolwrite.com: sign up, add credits, then open API Keys and create a key. An agent cannot do this for you.
Put the key in your shell profile (~/.zshrc, ~/.bashrc) so every agent session you start can read it, then open a new terminal:
export KOLWRITE_API_KEY=... # paste the key from API Keys
The tools read the key only from this variable. Do not paste it into a chat or commit it to a repository.
Add the MCP server
Run this in a terminal where KOLWRITE_API_KEY is set. Add --scope user to have it in every project:
claude mcp add --transport stdio --env KOLWRITE_API_KEY="$KOLWRITE_API_KEY" kolwrite -- npx -y https://console.kolwrite.com/mcp/kolwrite-mcp-0.1.0.tgz
The server gives the agent six tools: transcribe_file, transcribe_url, upload_file, get_job, list_models, list_languages. It runs on your computer with Node.js 18 or newer and is fetched from https://console.kolwrite.com/mcp/kolwrite-mcp-0.1.0.tgz (SHA-256 0dcd6ff169b860b9363044837b8545279efa585c4987b20d81035f920f6ac7ca).
Check it with claude mcp list, or /mcp inside a session.
Or install the agent skill
The skill is a folder with a SKILL.md and the one-file client. Claude Code loads it from ~/.claude/skills (every project) or .claude/skills (one project) and uses it when you ask for a transcription:
mkdir -p ~/.claude/skills && cd ~/.claude/skills
curl -fsSLO https://console.kolwrite.com/skills/kolwrite-transcribe.zip && unzip -o kolwrite-transcribe.zip && rm kolwrite-transcribe.zip
The skill text is at SKILL.md. Use the MCP server or the skill; you do not need both.
What to ask
Three things to ask Claude Code:
Transcribe ~/Downloads/interview.m4a with KolWrite and save the text as interview.txt next to it.
Make English SRT subtitles for talk.mp4 with KolWrite, one cue per sentence.
Who said what in team-call.mp3? Transcribe it with speaker labels on the oracle model, then list each speaker's action items.
Claude Code needs the file on your computer or a direct link to a media file. For video longer than about 100 MiB it extracts the audio with ffmpeg first.
What it costs
| Job | Model | Cost |
|---|---|---|
| A 30-minute interview, plain text | base | US$0.24 |
| A one-hour meeting with speaker labels | oracle | US$1.56 |
| A one-hour Hebrew talk with English subtitles | oracle | US$1.44 |
| One hour of noisy, overlapping audio | oracle_max | US$3.60 |
Billed per second of audio from your credits, with no minimum. Speaker labels add 0.10 credits per audio hour. The MCP server and kolwrite.py pick base unless you or the agent name another model, and oracle_mini when translating. Full rates: /models.
What the agent must not do
- Ask you for the key in the chat, print it, or write it into a file, a command or a commit.
- Start the same transcription again after a timeout or a network error. Each start is a new job that is billed; it should check the job instead, or ask you.
- Type timestamps itself. To cut or quote by time it takes segment numbers from the transcript and computes the times in code from the word timings.
- Send a YouTube or other web page address as the media. It needs the media file itself.
- Transcribe long recordings (over an hour) without telling you the expected cost first.
Questions and answers
Does Claude Code need the MCP server, or can it call the API itself?
It can call the REST API itself with curl or Python if you add the rule from agent-instructions.md to CLAUDE.md. The MCP server or the skill saves it from writing the upload and polling code each time.
Where does the audio go?
The file is uploaded to KolWrite and transcribed in the cloud under the KolWrite terms and privacy policy. The MCP server keeps no copy.