talkthrough-mcp

# talkthrough-mcp

<!-- mcp-name: io.github.korovin-aa97/talkthrough-mcp -->

[![ci](https://github.com/korovin-aa97/talkthrough-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/korovin-aa97/talkthrough-mcp/actions/workflows/ci.yml)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![python](https://img.shields.io/badge/python-3.11%E2%80%933.13-blue.svg)](pyproject.toml)
[![PyPI](https://img.shields.io/pypi/v/talkthrough-mcp.svg)](https://pypi.org/project/talkthrough-mcp/)

[Quickstart](#quickstart) · [Tools](#tools) · [Benchmarks](benchmarks/) ·
[FAQ](#faq) · [Troubleshooting](docs/TROUBLESHOOTING.md) ·
[Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)

# Don't write a bug report. Record it.

Give Claude Code or Codex a narrated `.mov`/`.mp4` — talkthrough turns it
into searchable transcript, exact frames, OCR and wall-clock timestamps,
locally — so your agent files an evidence-backed issue or investigates the fix.

Also works for meetings, workshops, product demos, and production incidents.

![talkthrough demo: a recorded checkout bug goes through /talkthrough:bug — indexed locally, evidence found, and filed as an issue](assets/demo.gif)

*One `/talkthrough:bug` run: the recording is indexed locally (transcript ·
keyframes · OCR · wall-clock), the evidence checkpoint is assembled, and the
bug lands in the tracker with the screenshot attached.*

**[▶ Watch the demo with sound (1:18)](https://youtu.be/nHfGfEiVdE8)** — a
real, unedited session: a narrated recording goes in, a ready-to-file
`bug-report.md` comes out.

## Quickstart

One command, no system dependencies: ffmpeg falls back to a bundled build,
OCR is pip-only, and whisper models download themselves on first use. The
only prerequisite is [uv](https://docs.astral.sh/uv/) (`brew install uv` or
`curl -LsSf https://astral.sh/uv/install.sh | sh`).

<!-- gen:install — generated by scripts/gen_integrations.py; do not hand-edit -->

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=talkthrough&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ0YWxrdGhyb3VnaC1tY3BbZGlhcml6YXRpb25dIl19)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=talkthrough&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22talkthrough-mcp%5Bdiarization%5D%22%5D%2C%22type%22%3A%22stdio%22%7D)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=talkthrough&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22talkthrough-mcp%5Bdiarization%5D%22%5D%2C%22type%22%3A%22stdio%22%7D&quality=insiders)
[![Add to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=talkthrough&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ0YWxrdGhyb3VnaC1tY3BbZGlhcml6YXRpb25dIl19)
[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=talkthrough&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22talkthrough-mcp%5Bdiarization%5D%22%5D%7D)

### Claude Code

Two install paths — **pick one**, not both (the plugin already includes
the server; installing both would register it twice):

**Server only** — the 7 tools + 6 prompts, and nothing else on your
system. Choose this for a minimal setup, or when you manage MCP servers
yourself across several clients:

```bash
claude mcp add -s user talkthrough -- uvx "talkthrough-mcp[diarization]"
```

**Full plugin** — the same server, plus native slash commands
(`/talkthrough:bug`, `/talkthrough:triage-recording`, …) that handle the
ceremony for you, a ready-made triage subagent, and an agent skill that
teaches Claude the workflow. Choose this for the best out-of-the-box
experience:

```
/plugin marketplace add korovin-aa97/talkthrough-mcp
/plugin install talkthrough@talkthrough
```

### Every other MCP client

<details>
<summary><b>Claude Desktop</b></summary>

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "talkthrough": {
      "command": "uvx",
      "args": [
        "talkthrough-mcp[diarization]"
      ]
    }
  }
}
```

More: [`integrations/claude-desktop/`](integrations/claude-desktop/)

</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json (or project .cursor/mcp.json)`:

```json
{
  "mcpServers": {
    "talkthrough": {
      "command": "uvx",
      "args": [
        "talkthrough-mcp[diarization]"
      ]
    }
  }
}
```

More: [`integrations/cursor/`](integrations/cursor/)

</details>

<details>
<summary><b>OpenAI Codex CLI</b></summary>

`~/.codex/config.toml (or project-scoped .codex/config.toml in trusted projects)`:

```toml
[mcp_servers.talkthrough]
command = "uvx"
args = ["talkthrough-mcp[diarization]"]
```

More: [`integrations/codex/`](integrations/codex/)

</details>

<details>
<summary><b>Gemini CLI</b></summary>

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "talkthrough": {
      "command": "uvx",
      "args": [
        "talkthrough-mcp[diarization]"
      ]
    }
  }
}
```

More: [`integrations/gemini-cli/`](integrations/gemini-cli/)

</details>

<details>
<summary><b>Cline / Roo Code</b></summary>

`cline_mcp_settings.json (via MCP Servers UI)`:

```json
{
  "mcpServers": {
    "talkthrough": {
      "command": "uvx",
      "args": [
        "talkthrough-mcp[diarization]"
      ]
    }
  }
}
```

More: [`integrations/cline/`](integrations/cline/)

</details>

<details>
<summary><b>OpenClaw</b></summary>

`~/.openclaw/openclaw.json`:

```json
{
  "mcp": {
    "servers": {
      "talkthrough": {
        "command": "uvx",
        "args": [
          "talkthrough-mcp[diarization]"
        ]
      }
    }
  }
}
```

More: [`integrations/openclaw/`](integrations/openclaw/)

</details>

<details>
<summary><b>OpenCode</b></summary>

`opencode.json (project) or ~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "talkthrough": {
      "type": "local",
      "command": [
        "uvx",
        "talkthrough-mcp[diarization]"
      ],
      "enabled": true
    }
  }
}
```

More: [`integrations/opencode/`](integrations/opencode/)

</details>

<details>
<summary><b>Goose</b></summary>

`~/.config/goose/config.yaml`:

```yaml
extensions:
  talkthrough:
    enabled: true
    type: stdio
    cmd: uvx
    args: ["talkthrough-mcp[diarization]"]
```

More: [`integrations/goose/`](integrations/goose/)

</details>

<details>
<summary><b>GitHub Copilot CLI</b></summary>

`~/.copilot/mcp-config.json`:

```json
{
  "mcpServers": {
    "talkthrough": {
      "command": "uvx",
      "args": [
        "talkthrough-mcp[diarization]"
      ]
    }
  }
}
```

More: [`integrations/copilot-cli/`](integrations/copilot-cli/)

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "talkthrough": {
      "command": "uvx",
      "args": [
        "talkthrough-mcp[diarization]"
      ]
    }
  }
}
```

More: [`integrations/windsurf/`](integrations/windsurf/)

</details>

<details>
<summary><b>Zed</b></summary>

`settings.json (Zed)`:

```json
{
  "context_servers": {
    "talkthrough": {
      "source": "custom",
      "command": {
        "path": "uvx",
        "args": [
          "talkthrough-mcp[diarization]"
        ]
      }
    }
  }
}
```

More: [`integrations/zed/`](integrations/zed/)

</details>

Any other MCP stdio client uses the same server command: `uvx "talkthrough-mcp[diarization]"`.
Per-engine folders with exactly these snippets plus verification steps live
in [`integrations/`](integrations/); agents can self-install via
[`llms-install.md`](llms-install.md).

<!-- /gen:install -->

### Who said what (speaker diarization) — included in the configs above

Multi-person recordings (meetings, interviews, panels) can carry `S1`/`S2`/…
speaker labels. Every install button, snippet, and the plugin above already
ship the `[diarization]` engine, so asking your agent "who said what" just
works — diarization itself still runs only when requested per call
(`process_media(path=..., diarize=true, num_speakers=<count if known>)`),
and its models download once on first use.

Prefer the minimal server without the diarization engine? Use
`uvx talkthrough-mcp` as the command instead (the MCP registry entry also
resolves to this lean form) — an explicit `diarize=true` will then answer
with the one-line install fix. Details in
[Speakers](#speakers-optional-diarization).

### Local checkout (development)

```bash
git clone https://github.com/korovin-aa97/talkthrough-mcp
claude mcp add talkthrough -- uv run --directory /path/to/talkthrough-mcp talkthrough-mcp
```

Then, in your agent:

> Process `~/Desktop/recording.mov` and triage it — or just invoke the
> `triage-recording` server prompt.

## Tools

| Tool | What it does |
|---|---|
| `process_media(path, recorded_at?, vocabulary?, language?, model?, diarize?, num_speakers?, force?)` | Ingest a video/audio file: local STT, keyframes, OCR, wall-clock, opt-in speaker labels. Returns a compact summary. Idempotent by content hash — re-calls are instant; `diarize=true` on a processed job adds speakers without re-transcribing. |
| `get_transcript(job_id, start_ms?, end_ms?, format?)` | Paginated transcript as `segments`, `text`, or `srt` (speaker-prefixed when diarized, plus a roster header); truncation returns `next_start_ms`. |
| `get_frames(job_id, at_ms? \| start_ms?+end_ms?, max_frames?, include_duplicates?)` | Keyframe images nearest a timestamp or evenly thinned across a range (unique frames by default, max 6/call); each frame names its absolute `path`. |
| `get_moment(job_id, start_ms, end_ms)` | The "one remark" bundle: transcript slice + up to 3 frames + their OCR text + wall-clock range (+ `speakers_in_range` when