transcribe.so

將YouTube影片、播客、會議及檔案轉錄為帶有說話者標記和時間戳的逐字稿。搜尋誰說了什麼、提出有引用的問題、匯出章節、字幕及隱藏式字幕。託管遠端伺服器，支援OAuth。

託管 MCP 伺服器

npx add-mcp 'https://transcribe.so/mcp'

可安裝到 Claude Code、Codex、Cursor 等客戶端

文件

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"}}}

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.

ChatGPT

Settings, Connectors, Developer mode, then add https://transcribe.so/mcp. Or use the public Custom GPT linked from https://transcribe.so/agent, which needs no setup.

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 $0.05 per started 60 s. Live Q&A uses a daily allowance, never the wallet. Details: 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.

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.