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` — or a public video link —
and talkthrough turns it into searchable transcript, exact frames, OCR and
wall-clock timestamps, locally — so your agent writes an evidence-backed
issue draft or investigates the fix.

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

![Illustration of a /talkthrough:bug run: a recorded checkout bug is indexed locally, the evidence is found, and a ready-to-file issue draft is assembled](assets/demo.gif)

*Illustration — an animation of the `/talkthrough:bug` storyline, not a screen
capture: the recording is indexed locally (transcript · keyframes · OCR ·
wall-clock), the evidence checkpoint is assembled, and the draft is ready to
file with your own tracker tooling (`gh`, Jira, a GitHub MCP server —
talkthrough itself never leaves your machine and never posts anything).*

**Real runs, no animation:**

- **[▶ Watch the demo with sound (1:18)](https://youtu.be/nHfGfEiVdE8)** — an
  unedited session: a narrated recording goes in, a ready-to-file
  `bug-report.md` comes out.
- **[Silent recording → issue draft](examples/bug-from-silent-recording/)** —
  the whole thing as files you can re-run: a Playwright-recorded, audio-free
  `.mp4` and the unedited agent output. Every number is reproducible —
  processing that file gives `job_id 8703a66bbe77a7d0` (the job id *is* the
  sha256 prefix, so `shasum -a 256` predicts it), 17 keyframes / 4 unique, and
  0 transcript segments because there is no audio track.

## 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`).

Cold setup has two separate stages: `uvx` first resolves a compatible Python
and the pinned server environment, then the first `process_media` downloads
any missing media/model assets. A plugin update can create a new environment
and, without system ffmpeg, fetch the ~80 MB bundled ffmpeg again; shared
Whisper/OCR/diarization caches and warm, network-free jobs remain reusable.
See [Troubleshooting](docs/TROUBLESHOOTING.md#first-run-is-slow--downloads-a-lot).

<!-- 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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLXB5dGhvbiIsIj49My4xMSw8My4xNCIsInRhbGt0aHJvdWdoLW1jcFtkaWFyaXphdGlvbix1cmxdIl19)
[![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%22--python%22%2C%22%3E%3D3.11%2C%3C3.14%22%2C%22talkthrough-mcp%5Bdiarization%2Curl%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%22--python%22%2C%22%3E%3D3.11%2C%3C3.14%22%2C%22talkthrough-mcp%5Bdiarization%2Curl%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=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLXB5dGhvbiIsIj49My4xMSw8My4xNCIsInRhbGt0aHJvdWdoLW1jcFtkaWFyaXphdGlvbix1cmxdIl19)
[![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%22--python%22%2C%22%3E%3D3.11%2C%3C3.14%22%2C%22talkthrough-mcp%5Bdiarization%2Curl%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 9 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 --python ">=3.11,<3.14" "talkthrough-mcp[diarization,url]"
```

**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": [
        "--python",
        ">=3.11,<3.14",
        "talkthrough-mcp[diarization,url]"
      ]
    }
  }
}
```

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": [
        "--python",
        ">=3.11,<3.14",
        "talkthrough-mcp[diarization,url]"
      ]
    }
  }
}
```

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 = ["--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]"]
```

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

</details>

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

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "talkthrough": {
      "command": "uvx",
      "args": [
        "--python",
        ">=3.11,<3.14",
        "talkthrough-mcp[diarization,url]"
      ]
    }
  }
}
```

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": [
        "--python",
        ">=3.11,<3.14",
        "talkthrough-mcp[diarization,url]"
      ]
    }
  }
}
```

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

</details>

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

`~/.openclaw/openclaw.json`:

```json
{
  "mcp": {
    "servers": {
      "talkthrough": {
        "command": "uvx",
        "args": [
          "--python",
          ">=3.11,<3.14",
          "talkthrough-mcp[diarization,url]"
        ]
      }
    }
  }
}
```

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",
        "--python",
        ">=3.11,<3.14",
        "talkthrough-mcp[diarization,url]"
      ],
      "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: ["--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]"]
```

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

</details>

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

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

```json
{
  "mcpServers": {
    "talkthrough": {
      "command": "uvx",
      "args": [
        "--python",
        ">=3.11,<3.14",
        "talkthrough-mcp[diarization,url]"
      ]
    }
  }
}
```

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": [
        "--python",
        ">=3.11,<3.14",
        "talkthrough-mcp[diarization,url]"
      ]
    }
  }
}
```

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": [
          "--python",
          ">=3.11,<3.14",
          "talkthrough-mcp[diarization,url]"
        ]
      }
    }
  }
}
```

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

</details>

Any other MCP stdio client uses the same server command: `uvx --python ">=3.11,<3.14" "talkthrough-mcp[diarization,url]"`.
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`/…
spea