Subtitles King

MCP server reference

The Subtitles King MCP server exposes four tools that cover the full upload → status → download lifecycle. Video bytes never travel through the LLM context. start_upload returns a presigned upload URL the agent hits directly with curl; get_download_url does the same on the way out.

The MCP ships in two transports that expose identical tool surfaces by construction:

  • Hosted HTTP MCP — https://brains.subtitlesking.com/mcp, streamable-HTTP transport.
  • Stdio MCP — open-source Go binary, JSON-RPC over stdin/stdout. The binary is a thin proxy to the hosted (or your own) upload server.

Pick whichever fits your client.

Install

Hosted (HTTP MCP)

Most modern MCP clients support streamable-HTTP. Register the URL and you're done.

Claude Code

claude mcp add --transport http subtitlesking https://brains.subtitlesking.com/mcp

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "subtitlesking": {
      "url": "https://brains.subtitlesking.com/mcp"
    }
  }
}

Cursor

.cursor/mcp.json in your project:

{
  "mcpServers": {
    "subtitlesking": {
      "url": "https://brains.subtitlesking.com/mcp"
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "subtitlesking": {
      "url": "https://brains.subtitlesking.com/mcp"
    }
  }
}

Local stdio binary

Prebuilt binary (recommended):

# macOS arm64
curl -L https://github.com/kirillzubovsky/subtitlesking-mcp/releases/latest/download/subtitlesking-mcp-darwin-arm64.tar.gz \
  | tar -xz
sudo mv subtitlesking-mcp /usr/local/bin/

Or build from source:

git clone https://github.com/kirillzubovsky/subtitlesking-mcp
cd subtitlesking-mcp
go build -o subtitlesking-mcp .
sudo mv subtitlesking-mcp /usr/local/bin/

Then point your client at the binary:

claude mcp add subtitlesking /usr/local/bin/subtitlesking-mcp

The binary is a JSON-RPC stdio↔HTTP bridge. Every request from stdin is POSTed verbatim to <SUBTITLESKING_URL>/mcp and the response written back to stdout. No per-tool logic in the binary — the upload server is the single source of truth.

| Variable | Default | Purpose | |---|---|---| | SUBTITLESKING_URL | https://brains.subtitlesking.com | Backend HTTP API to forward to. Set to http://localhost:8080 for fully self-hosted use. |

Tools

start_upload

Reserve an upload slot. Returns a presigned upload_url and a copy-paste curl_example. The agent runs the curl itself; bytes go disk-to-server without entering the LLM context.

Arguments:

  • filename (string, required) — the original filename with extension, e.g. clip.mp4. The actual upload happens via the returned upload_url; the multipart file field's filename is what the server records as authoritative.

Example:

{
  "name": "start_upload",
  "arguments": { "filename": "clip.mp4" }
}

Returns: A text content block with video_id, auth_token, upload_url, expires_at, max_bytes, and a ready-to-paste curl -F file=@… example. The presigned upload URL is valid for 1 hour.

get_video_status

Look up the current pipeline status by auth_token.

Arguments:

  • auth_token (string, required) — the 8-digit token from start_upload.

Example:

{
  "name": "get_video_status",
  "arguments": { "auth_token": "12345678" }
}

Returns: Status string and queue position. When status is srt_generated or later, a transcript_url is included. When status is subtitles_burned, a download_url is included too.

get_transcript

Return the SRT transcript inline as text. Available as soon as status reaches srt_generated (typically a couple of minutes before the burned video).

Arguments:

  • auth_token (string, required).

Returns: Inline SRT text.

get_download_url

Return a 24-hour presigned URL for the finished, subtitle-burned video. The agent fetches the file out-of-band (e.g. curl -o).

Arguments:

  • auth_token (string, required).

Example:

{
  "name": "get_download_url",
  "arguments": { "auth_token": "12345678" }
}

Returns: A text content block with download_url, expires_at, and a ready-to-paste curl -o example.

Status states

pending_upload     → slot reserved, bytes not yet received
new                → bytes received, queued for processing
compressing → compressed
generating_srt → srt_generated   (transcript ready)
burning_subtitles → subtitles_burned   (video ready)

error_* is emitted if any step fails. Rows stuck in pending_upload are pruned automatically after 1 hour.

Migration from v1

If you previously used add_subtitles_to_video or download_subtitled_video, they now return a structured deprecation error pointing at the new tools. Switch to start_upload (which returns an upload_url) and get_download_url (which returns a download_url). Bytes never travel through the LLM in either direction.

Protocol details

JSON-RPC 2.0. The stdio binary uses newline-delimited JSON-RPC over stdin/stdout. The hosted MCP uses streamable-HTTP: POST one JSON-RPC request, receive one response.

Spec: modelcontextprotocol.io.

Next steps