@transcriptdock/mcp

TranscriptDock MCP server

An MCP server that wraps the TranscriptDock public API, so Claude, Cursor and other agents can submit transcription jobs and read back transcripts without you leaving the chat.

It only calls the existing /v1 API described in docs/04-api.md. You need a TranscriptDock API key (td_live_...).

Remote (no install)

The hosted server is https://www.transcriptdock.com/mcp (Streamable HTTP). Use that exact URL: the apex domain redirects, and clients drop the Authorization header on a cross origin redirect.

Claude (claude.ai, Desktop, mobile)

Open Customize, Connectors, choose Add custom connector, and paste https://www.transcriptdock.com/mcp. Choose Add, then Connect, sign in to TranscriptDock and allow access. No API key needed: the server publishes RFC 9728 metadata and signs people in through OAuth 2.1 (dynamic client registration, S256 PKCE). An OAuth connection can read and submit jobs and read transcripts, nothing else.

Claude Code and other clients

claude mcp add --transport http transcriptdock https://www.transcriptdock.com/mcp

Then run /mcp and choose Authenticate. To use an API key instead, send it as a bearer header:

claude mcp add --transport http transcriptdock https://www.transcriptdock.com/mcp \
  --header "Authorization: Bearer td_live_..."

{ "mcpServers": { "transcriptdock": { "url": "https://www.transcriptdock.com/mcp", "headers": { "Authorization": "Bearer td_live_..." } } } }

Ask for a video and the agent calls get_video_transcript(url): submit, wait, text back in one tool call.

Install locally (npx)

Claude Desktop (stdio)

Claude Desktop users can add the remote connector above instead. For the local server, add this to your Claude Desktop config (Settings, Developer, Edit config):

{
  "mcpServers": {
    "transcriptdock": {
      "command": "npx",
      "args": ["-y", "@transcriptdock/mcp"],
      "env": {
        "TRANSCRIPTDOCK_API_KEY": "td_live_...",
        "TRANSCRIPTDOCK_BASE_URL": "https://www.transcriptdock.com"
      }
    }
  }
}

Claude Code

claude mcp add --transport stdio transcriptdock --env TRANSCRIPTDOCK_API_KEY=td_live_... --env TRANSCRIPTDOCK_BASE_URL=https://www.transcriptdock.com -- npx -y @transcriptdock/mcp

Cursor

Add a server in Cursor Settings, MCP, using the same command and environment variables:

{
  "mcpServers": {
    "transcriptdock": {
      "command": "npx",
      "args": ["-y", "@transcriptdock/mcp"],
      "env": {
        "TRANSCRIPTDOCK_API_KEY": "td_live_...",
        "TRANSCRIPTDOCK_BASE_URL": "https://www.transcriptdock.com"
      }
    }
  }
}

Launch mode

TranscriptDock is captions only for now: the transcribe tool accepts YouTube or TikTok URLs with mode defaulting to captions_only. Speech recognition (auto/transcribe modes) needs a paid plan, so the trial answers 402 PLAN_REQUIRED; anything the deployment has switched off, such as Instagram, answers 422 CAPABILITY_UNAVAILABLE. For local development use a loopback URL such as http://127.0.0.1:3000 for TRANSCRIPTDOCK_BASE_URL.

Configuration

Variable	Required	Purpose
TRANSCRIPTDOCK_API_KEY	yes	Your workspace API key. The server exits with a clear message if it is missing.
TRANSCRIPTDOCK_BASE_URL	yes	Explicit HTTPS API origin, https://www.transcriptdock.com. HTTP is allowed only for loopback local development.

Tools

• get_video_transcript: submit, wait and return the transcript text (or srt, vtt, segments) in one call. Example prompt: "What does this video say?"
• transcribe: submit a video or audio URL and get back the created job. Example prompt: "Transcribe this YouTube link and give me the SRT."
• get_job: look up a job's status, stage, error, and billing by ID. Example prompt: "Check on job 11111111-1111-4111-8111-111111111111."
• get_transcript: fetch a completed transcript as normalized JSON segments or as a text, SRT, or VTT export. Example prompt: "Get the VTT for transcript 22222222-2222-4222-8222-222222222222."
• list_jobs: list jobs for the workspace, newest first, with cursor pagination. Example prompt: "Show my last 10 transcription jobs."
• wait_for_job: poll a job every few seconds until it succeeds, fails, or is cancelled, then return it. Example prompt: "Transcribe this TikTok and wait until it is done."
• search_youtube: search YouTube by query with cursor paging. Example prompt: "Search YouTube for lofi study music and transcribe the top result"
• list_channel_videos: list videos from one channel with cursor paging. Example prompt: "List the latest videos from @veritasium"
• get_channel_latest_videos: get the latest videos from one channel newest first with no cursor input. Example prompt: "Find the latest five videos on @veritasium and transcribe the first one"
• search_channel_videos: search within one channel by query with cursor paging. Example prompt: "Search @veritasium for black holes and transcribe the best match"
• list_playlist_videos: list videos from one playlist with cursor paging. Example prompt: "List the videos in this playlist and transcribe the first one"
• list_tiktok_user_videos: list up to 10 videos from one TikTok profile with the profile stats. TikTok search and further pages are not available. Set include_details to fetch each video page for full stats, dates, hashtags, and music. Example prompt: "List the latest TikTok videos from @tiktokuser"
• get_video_discovery: get one video discovery by ID. Example prompt: "Check on my latest video discovery and show the video list"

Each listing tool creates one video discovery with a generated idempotency key then polls to completion with a bounded timeout. A timeout returns the last body with a flag and a hint to call get_video_discovery. A failed discovery returns an error result with the error object.

Every response is the raw API payload, pretty printed as JSON, except get_transcript with format: text, srt, or vtt, which returns the export file body directly. API errors come back as a readable tool error with the error code, message, and request ID; the API key is never included in output.

Development

pnpm install
pnpm --filter @transcriptdock/mcp typecheck
pnpm --filter @transcriptdock/mcp build
pnpm --filter @transcriptdock/mcp test
pnpm --filter @transcriptdock/mcp dev