transcribe.so

transcribe-agent

Make any agent transcribe. One repo with three ways in: a pure-JSON CLI (transcribe-so), an agent skill for npx skills add, and a Claude Code plugin bundling the transcribe.so remote MCP server.

transcribe.so turns YouTube videos, podcasts, direct media URLs, and local files into speaker-labelled transcripts with timestamped segments, chapters, sections, cited Q&A, subtitle files (SRT, VTT, karaoke VTT), full transcript exports, segment search, and paste-ready captions for Instagram, X, Threads, LinkedIn, YouTube, Spotify and Apple Podcasts.

Install

Keep a human in the loop: every paid call takes a max_charge_usd ceiling, and a free quote comes first.

1. Agent skill (Claude Code, OpenClaw, any skills.sh-compatible agent)

npx skills add shsunmoonlee/transcribe-agent

This installs SKILL.md, which teaches the agent the CLI workflow, hard rules, and exit codes.

2. Claude Code plugin (remote MCP server + skills + /transcribe command)

/plugin marketplace add shsunmoonlee/transcribe-agent
/plugin install transcribe-so@transcribe-agent

The plugin connects Claude to the remote MCP server at https://transcribe.so/mcp (24 tools) and bundles the transcribe-audio and get-transcript skills plus a one-shot /transcribe command. First tool call triggers the OAuth browser flow; alternatively authenticate with a tsk_live_* API key via /mcp.

3. CLI (any script, cron job, or agent with a shell)

npm install -g transcribe-so     # or: pnpm install -g transcribe-so
export TRANSCRIBE_API_KEY=tsk_live_...   # https://transcribe.so/settings/api-keys
transcribe-so me

Codex

As a plugin (remote MCP server plus the skills):

codex plugin marketplace add shsunmoonlee/transcribe-agent
codex plugin add transcribe-so@transcribe-agent

Or just the MCP server:

codex mcp add transcribe --url https://transcribe.so/mcp

Codex opens the OAuth flow on the first tool call. The plugin ships .codex-plugin/plugin.json and .agents/plugins/marketplace.json.

Grok

This repo ships .grok-plugin/plugin.json; Grok Build reads the root .mcp.json and skills/ from it.

Cursor

From the marketplace or the Customize panel: find transcribe-so and click Install. Or add it to .cursor/mcp.json by hand:

{"mcpServers":{"transcribe":{"url":"https://transcribe.so/mcp"}}}

Antigravity CLI

agy plugin install https://github.com/shsunmoonlee/transcribe-agent

The plugin ships plugin.json and mcp_config.json, which point Antigravity CLI at the hosted MCP server, plus the skills in skills/. Antigravity CLI cannot run the OAuth sign-in itself (its /mcp panel shows "Auth Needed"), so connect the tools with an API key from https://transcribe.so/settings/api-keys:

agy mcp add --header "Authorization: Bearer tsk_live_..." transcribe-so-key https://transcribe.so/mcp

Use a name other than transcribe-so: MCP server names are global in Antigravity, and the plugin's own transcribe-so entry keeps showing "Auth Needed" in the CLI, which you can ignore. The Antigravity App and IDE also offer an Authenticate button for the plugin's server (Settings, Customizations). Already used the Gemini CLI extension? agy plugin import gemini converts it.

Gemini CLI

gemini extensions install https://github.com/shsunmoonlee/transcribe-agent

The extension ships gemini-extension.json, which points Gemini CLI at the hosted MCP server. It opens a browser to sign in on first use. Since 2026-06-18 Gemini CLI serves paid Gemini API and enterprise keys; individual Google AI accounts use Antigravity CLI (above).

ChatGPT

Settings, Connectors, Developer mode, then add https://transcribe.so/mcp and sign in with your transcribe.so account.

OpenClaw and any skills.sh agent

npx skills add shsunmoonlee/transcribe-agent

Same command as entry 1 above: the skill is runtime-agnostic and teaches the CLI workflow, hard rules, and exit codes.

CLI in 30 seconds

# Price it (free), then transcribe under an explicit budget
transcribe-so quote --source youtube --url "https://www.youtube.com/watch?v=..."
transcribe-so run   --source youtube --url "https://www.youtube.com/watch?v=..." --max-usd 2

# Local file
transcribe-so upload ./interview.mp3         # prints upload_id (+ ffprobe duration)
transcribe-so run --source upload --upload-id <id> --duration <s> --max-usd 5

# Artifacts
transcribe-so result <id> | jq '.chapters[]'
transcribe-so transcript <id> > out.txt                      # the whole transcript, never capped
transcribe-so subtitles <id> --format srt > out.srt
transcribe-so captions <id> --for instagram --variant highlights
transcribe-so search "pricing" | jq -r '.hits[] | "\(.speaker): \(.text)"'
transcribe-so ask <id> -q "What did the guest say about pricing?"

Commands

Command	What it does
auth:status	Is TRANSCRIBE_API_KEY valid?
me	Account, wallet balance, plan limits, API-key scopes and spend
capabilities	One JSON object: account + pipeline catalog + every format enum + exit codes
pipelines	Per-minute pricing and supported languages
quote	Free price preview (does not queue anything)
create	Submit a job. --max-charge-usd <n> caps the charge server-side
run	quote → budget gate → create → wait → result, in one command
wait <id>	Long-poll to a terminal status
result <id>	Chapters, sections, Q&A (--include, --segments-offset, --segments-limit)
transcript <id>	Raw: the complete transcript, txt or md, never capped
subtitles <id>	Raw: SRT / VTT / karaoke VTT / JSON
captions <id> --for <dest>	Raw: paste-ready caption or chapter timestamps per platform
search <q>	"Who said X, and when", library-wide or --id-scoped
ask <id> -q "..."	Cited Q&A (daily allowance, never the wallet)
list / get <id>	Browse jobs; status/stage/progress snapshot
upload <file>	Presigned PUT for a local file; prints upload_id
retry <id> --yes	New paid attempt (pass --max-charge-usd again)
delete <id> --yes	Irreversible

Design contract, made for agents:

• stdout is JSON everywhere except the three raw-output commands (subtitles, transcript, and captions without --json), which print a body you can pipe to a file. Errors are always the JSON envelope. All progress goes to stderr, so | jq . always works.
• Exit codes are meaningful: 0 ok, 1 API error, 2 usage, 3 auth, 4 payment, 5 transient, 6 local --max-usd budget refusal, 7 server-side max_charge_exceeded (nothing charged, no job started).
• Two budgets, both explicit: run --max-usd refuses locally from the free quote; --max-charge-usd is sent to the API and enforced at the wallet hold. run sends its --max-usd as the server ceiling too unless you pass --no-server-ceiling.
• create/run/quote/retry always send an Idempotency-Key. Pass --idempotency-key explicitly to make a retry safe across processes: the auto-generated one is per invocation, so re-running a command is a second key and a second charge.
• A 409 not_ready is acted on by its reason: only transcription_processing is ever retried.
• The CLI refuses to send your API key to a non-default host unless you pass --allow-custom-host.

Full command reference and workflow rules: SKILL.md. Release notes: CHANGELOG.md. Worked examples: examples/.

Pricing

Transcription is billed per minute from your transcribe.so wallet; quotes are free (quote before committing). Clip renders are billed per started 60 s. Live Q&A uses a daily allowance, never the wallet. Current prices: https://transcribe.so/pricing

Directories

The plugin manifests (.codex-plugin, .claude-plugin, .cursor-plugin, .grok-plugin, gemini-extension.json) are versioned together and track the MCP server version; the CLI in package.json has its own version.

Build the OpenAI Plugins Directory submission ZIP:

pnpm run build:openai-plugin -- --video-url https://.../demo.mp4   # or DEMO_RECORDING_URL=...
# -> out/transcribe-so-openai-plugin.zip (.codex-plugin/plugin.json, .mcp.json, skills/, assets/)

The script fails when model-readable copy breaks the listing rule: the interface block, release notes, skills/**/SKILL.md, commands/*.md and every manifest description carry no money, promotion or account-tier wording, no em-dashes, and no links outside transcribe.so and github.com. The agent learns what getQuote reports and when to ask the user before starting, nothing more. It also fails when the manifests disagree on the version or when skills/ holds anything but <skill>/SKILL.md. Rules: https://developers.openai.com/plugins/plugin-guidelines.

The root SKILL.md documents the CLI for npx skills add and is not part of any directory listing; CLI flags such as --max-charge-usd live there.

What the Claude plugin runs and sends

• One remote MCP server, declared in .mcp.json: https://transcribe.so/mcp over HTTPS. Claude sends it the links, questions and transcript ids you give it, and it returns transcripts, chapters, answers, subtitle files and clip links. Sign-in is OAuth in your browser on the first tool call, or a transcribe.so API key you enter through /mcp.
• Local files, Claude Code only, when you ask for one: createUpload returns a short-lived presigned HTTPS URL for transcribe.so's file storage on Cloudflare R2 (an r2.cloudflarestorage.com address), and Claude sends the file there with an HTTP PUT. Chat clients never upload files.
• Nothing else: no hooks, no local server, no package downloads, no telemetry, and no credentials read from your machine. The skills and the /transcribe command are Markdown instructions for Claude.
• Starting a transcription or rendering a clip draws on your transcribe.so account balance. Claude checks the free quote first and asks before it starts anything, unless you already gave it a spending limit.

Privacy Policy

This tooling sends the media URLs, uploaded files, and questions you provide to transcribe.so for processing. See the transcribe.so privacy policy at https://transcribe.so/privacy-policy for data collection, usage, storage, retention, and contact information. No data is collected by the CLI or plugin itself beyond what the API and MCP tools transmit.

Links

• Agent landing page: https://transcribe.so/agent
• Docs: https://transcribe.so/developers/docs
• OpenAPI: https://transcribe.so/openapi.json
• MCP server card: https://transcribe.so/.well-known/mcp/server-card.json
• Auth guide: https://transcribe.so/auth.md
• Support: [email protected]