Docs Guides

MCP server

Add Podcli to Claude Code, Claude Desktop, Codex, or Cursor and clip podcasts by talking to the agent. The MCP server exposes the whole pipeline as tools.

Podcli ships as a Model Context Protocol server. Plug it into any MCP client and the agent runs the whole pipeline: transcribe, score clips against your knowledge base, crop, caption, and export. Say "clip this episode" and it does the rest.

Run podcli setup before podcli mcp. The MCP command does not provision, because stdout is JSON-RPC.

podcli mcp install registers the server with Claude Code and Codex, whichever CLI is on PATH. Clip scoring uses Claude Code or Codex login, or an Anthropic API key. Without those it falls back to heuristics.

For the marketing overview see the MCP page.

Add it to Claude Code#

Or register by hand:

Add it to Codex#

podcli mcp install registers with Codex too when the codex CLI is on PATH. To register by hand:

Add it to Cursor#

Project config, .cursor/mcp.json:

The same block goes in Claude Desktop's claude_desktop_config.json.

What you say to the agent#

Natural language. The agent reads the tool list and figures out the call sequence.

The manage_assets tool keeps a shared library of logos, outros, intros, and music. Register once and the agent (and the studio and CLI) can reference them by name in any render.

Privacy#

The MCP server runs locally as a process the agent talks to. The video, transcript, and renders stay on your machine. The only network calls are the optional Claude or Codex API calls when you use AI clip scoring.

SKILL.md#

SKILL.md in the podcli repo is the agent workflow: setup, the headless CLI, and the short MCP path so the agent does not load the full transcript.

Prefer the short path:

  1. transcribe_podcast (or transcribe_start + job_status on a long file)
  2. rank_clip_candidates(video_path) — about 20 sentence-aligned candidates
  3. Pick a subset. suggest_clips to store them, or create_clip / batch_create_clips to render
  4. list_outputs if you only need paths on disk

One-shot when the user wants finished files, not a review pass:

  1. process_episode(video_path)
  2. job_status(job_id, wait_seconds: 30) until done
  3. Read clip paths, durations, scores, titles, captions from result

Do not call get_ui_state(include_transcript: true) unless you need to rewrite a range; use rank_clip_candidates. Do not run podcli mcp as the first command on a fresh install; run podcli setup.

rank_clip_candidates, process_episode, and job_status#

rank_clip_candidates and process_episode require podcli 2.8.2 or later.

rank_clip_candidates returns a shortlist from the cached transcript so the agent does not have to read the whole thing. It does not call an AI CLI.

process_episode runs transcribe, rank, and render as one job. It returns { job_id } immediately and does not need the studio. The result is the same JSON podcli process --json prints.

job_status polls any background job (transcription, render, batch export, process_episode) with wait_seconds (default 30). Stop when done is true.

Tool reference#

32 tools, generated from the product repo's docs manifest.

Transcription and input

ToolWhat it does
transcribe_podcastTranscribe audio/video with Whisper word timestamps + speaker detection
transcribe_startStart transcription as a background job, returns a job_id immediately
job_statusPoll any background job (transcription, render, batch export, process_episode) with long-polling
set_videoSet the working video without transcribing
import_transcriptImport an external transcript with word-level timestamps, skips Whisper
parse_transcriptParse a speaker-labeled plain text transcript into word-level timestamps
compare_transcription_enginesTranscribe one sample with two engines and write a side-by-side disagreement report
mine_channelList a YouTube channel's uploads or mine one video's existing captions, without downloading the video

Clip workflow

ToolWhat it does
get_ui_stateRead session state (video, transcript, suggestions, settings) and next steps
rank_clip_candidatesReturn ~20 pre-ranked, sentence-aligned clip candidates from the cached transcript (no full transcript in the result)
process_episodeOne-shot job: transcribe, rank, render; poll with job_status and read clip paths from the result
suggest_clipsSubmit clip suggestions, assigns clip numbers, pushes them to the web UI
modify_clipAdjust a suggested clip: timing, title, caption style, or delete it
toggle_clipSelect or deselect a suggested clip for export
create_clipRender a single clip with burned-in captions and normalized audio
batch_create_clipsRender multiple clips in one batch
manage_reelBuild a highlights reel: detect once, edit moments, rebuild without re-detecting
analyze_energyAnalyze audio energy levels to find high-energy moments
record_decisionsRecord per-episode decisions (clip count, duration range, captions, language, thumbnails, delivery target) so later runs never re-ask

Full-episode editing

ToolWhat it does
manage_multicamMap camera, mic and call-recording files to people, sync them by audio, auto-cut to the speaker, render, export a studio shoot to Premiere / FCPXML, or hand the edit to the podcli cloud editor

Content and configuration

ToolWhat it does
knowledge_baseRead or manage the .podcli/knowledge/ context files
manage_assetsRegister and manage reusable assets: logos, intros, outros, music
clip_historyView previously created clips to avoid duplicates
list_outputsList rendered clip files with sizes and dates
update_settingsUpdate rendering settings: caption style, crop strategy, logo, outro
manage_presetsSave, load, list, or delete rendering presets
manage_thumbnail_configShow, export, import, or reset the thumbnail template

Integrations and environment

ToolWhat it does
manage_integrationsList, enable, or disable podcli integrations
export_to_davinci_resolveExport shorts as a DaVinci Resolve FCPXML project
manage_configManage portable config profiles and legacy path migration
manage_envList, set, or unset global podcli settings stored in .env
ai_cli_statusShow whether Claude Code / Codex CLIs are available for AI features