Transcription Salad MCP
MCP server for transcript-first transcription of audio files, YouTube videos, and public URLs, with optional frame analysis on demand.

Transcription Salad MCP is a server that connects AI clients to the Salad transcription infrastructure. An agent using Claude, Droid, Devin CLI, or Cursor can use the same interface to transcribe a local file, a YouTube video, or a public URL.

📋 Project metrics

• Start: July 2026
• Status: Production-ready v1
• Role: System Architect / Full-Stack Developer
• Goal: Make audio and video transcription available directly in MCP-capable AI clients
• Validation: A local MP3 file and a 38-minute YouTube video transcribed through a real MCP client

🚀 Product journey

1. Architecture: Designing a ports and adapters architecture with a clean functional core.
2. Foundation: Building the MCP server over stdio, source routing, configuration validation, and a unified error model.
3. Salad integration: Adding asynchronous transcription jobs, polling, a watchdog, and SRT retrieval.
4. Local files: Validation through ffprobe, SCP upload, temporary VPS storage, HTTPS verification, and automatic cleanup.
5. YouTube: Existing YouTube captions are downloaded first. Only when they are missing does the skill use Salad, relying on yt-dlp for the pre-check and audio-only extraction.
6. Validation: Unit, integration, and end-to-end tests with the real Salad API, a VPS, and yt-dlp.
7. Post-processing: The skill/watch/scripts/fix_srt_hallucinations.py script removes repetitions and cleans up the SRT transcript.

🎯 Business problem

AI clients can work with transcripts, but getting a good transcript from a local recording or a YouTube video often requires a separate, manual process.

The user has to download the material, find a transcription tool, upload the file, wait for the result, clean it up, and paste it back into the original conversation.

With larger files there is an additional problem: Salad needs a public URL, and local files are not publicly accessible.

❌ Pain points and operational challenges

• Manual work: Downloading, uploading, and moving transcripts between tools.
• Local files: An MCP client cannot directly expose a local file to a cloud API.
• Temporary storage: Large files must be publicly reachable, but should not stay online indefinitely.
• Long-running jobs: Transcription requires asynchronous polling instead of blocking the client.
• Imperfect output: Whisper can repeat fragments during silence or music.
• Different sources: Local files, YouTube URLs, and direct URLs require different preparation steps.

💡 Why it works (product approach)

• Single MCP interface: The client calls transcribe and get_transcription, regardless of the source type.
• Separate adapters: The URL, local file, and YouTube paths share a common Salad integration but keep their own validation.
• Temporary VPS: Local files and audio extracted from YouTube are stored under random UUID names and removed by cron after two hours.
• Transcript-first: The skill first uses YouTube's native captions and only runs Salad transcription when they are missing.
• Stateless polling: The server keeps no local job database. Salad remains the source of truth, and the client stores the job_id.
• Validation before the next step: Length, size, file type, VPS configuration, subprocess errors, and Salad responses are checked before moving to the next stage.
• SRT cleanup: The fixed script removes repeated fragments and tidies the result before handing the transcript to the agent.
• Transcript-first: The skill's default flow focuses on timestamped transcription and skips video frames. After an explicit user request, the skill can fetch frames via ffmpeg and pass them to the agent for reading.

📈 Impact on work (ROI)

“Instead of building a separate process around every recording, you can hand the source directly to the agent and get a finished SRT in the same context.”

🔗 Integration with the watch skill

The project ships with a dedicated watch skill, adapted to work with the Transcription Salad MCP server.

The watch skill is an adaptation of the bradautomates/claude-video project under the MIT license.

The skill works in transcript-first mode:

1. It first tries to fetch an existing transcript from YouTube.
2. If the material has no available captions, it runs transcription through Salad MCP.
3. The SRT result goes through the fixed fix_srt_hallucinations.py script, which removes typical looped repetitions and cleans up segment numbering.

In this flow, spoken content and timestamps come first. Frame analysis remains optional: after an explicit user request, the skill can fetch frames in keyframe, scene-aware, or timestamp-based mode, and pass them to the agent for reading.

🛠️ Architecture & tech stack

• Language: Python 3.13
• Protocol: MCP over stdio
• Transcription: Salad transcription-lite
• HTTP: httpx
• Media: yt-dlp, ffmpeg, ffprobe
• File transfer: OpenSSH, SCP
• Storage: nginx on a VPS
• Tests: pytest, unit tests with mocks, integration tests, and real E2E validation
• Architecture: Ports and adapters with a functional core

Server tools stay synchronous, and the MCP SDK runs them in separate worker threads. Long-running operations such as SCP, yt-dlp, and Salad polling block only a worker thread, not the server's main event loop. This keeps v1 simpler, without migrating the whole stack to async I/O.

🔒 Security and operational decisions

• API keys are loaded only from environment variables.
• Secrets, full local paths, and source URLs are never returned to the LLM.
• Local files are uploaded under random UUID names.
• Temporary files are served over HTTPS.
• Files on the VPS are automatically deleted after two hours.
• Subprocesses use argument lists and never shell=True.
• Direct URLs do not require VPS configuration.
• VPS configuration is validated only when the chosen source actually needs it.

✅ Validation

The project includes:

• 460 unit tests
• 5 integration tests
• 5 end-to-end tests with real infrastructure
• MCP stdio transport tests
• Salad API response and error mapping tests
• SCP, SSH, ffprobe, and yt-dlp tests
• security tests for path traversal, invalid input, and secret leakage

The first production validation confirmed two complete flows through a real MCP client:

1. Local MP3 file to SRT
2. YouTube video to SRT

🚀 Next steps

• Skill distribution and a simpler user onboarding.
• Review of the technical debt from the first version.
• Possible migration to full async I/O as a separate v2 stage.
• Further automation of configuration and project artifact synchronization.

Artefacts

• Source code: RafalWojciechRolsky/transcription-salad-mcp
• MCP server: transcription-salad-mcp
• Related skill: watch
• Transcription API: Salad