MCP Tvsubtitles

mcp-tvsubtitles

TVsubtitles.net catalogues subtitles for television series. Its readers upload a file for one episode, timed to one video release, and the site records the language, the release it was cut for, who uploaded it and when, how large the file is and how often it has been taken. It holds around three hundred thousand of them, across some eighty-six thousand episodes in twenty-four languages.

This server connects a chat client to that catalogue. You can search for a series, read a season and see which languages hold something for each episode, read the records of one episode, and open one record with the release it was cut for and who uploaded it. Every record carries the address of its page on the site. No API key and no account are needed.

_Version française_

Install

One-click install

Claude Code

claude mcp add tvsubtitles -- npx -y mcp-tvsubtitles

Any client reading `mcpServers`

{

"mcpServers": { "tvsubtitles": { "command": "npx", "args": ["-y", "mcp-tvsubtitles"] } } }

With Docker

{

"mcpServers": { "tvsubtitles": { "command": "docker", "args": ["run", "--rm", "-i", "ghcr.io/smeet666/mcp-tvsubtitles:1.1.0"] } } }

The container reaches https://www.tvsubtitles.net and nothing else.

Bundle, without npm

Download mcp-tvsubtitles.mcpb from the latest release and open it with a host that installs MCP bundles. It carries its dependencies, so Node 24 or later is all it needs.

What you can ask

• "Does tvsubtitles have French subtitles for Smallville?"
• "Which languages cover season 3 of Harbour Lights?"
• "List the English subtitles for episode 7 of that season."
• "Which release is that subtitle timed to, and who uploaded it?"
• "Find me the page to download the Polish subtitle for the finale."

Tools

search_titles

Searches the catalogue by name. The site catalogues television only, so a search for a film is refused rather than answered.

In return: the matching series, each with the id the other tools take, the years the site publishes, and the languages it draws a flag for. imdb_id and tmdb_id are null, because the site's search publishes none. subtitle_count, episode_count and season_count are null unless with_counts asks for them, since the site publishes those three on its catalogue index rather than on the page a search answers with; each counts every season of the show together, which counts_scope names, each is read on its own, and a show the index carries no row for keeps three nulls. total_available counts the rows this one search came back with, which total_counts names. A year that leaves nothing is set aside and named in filters_dropped.

list_subtitles

Reads what a series holds, in one of two shapes that kind names.

In return: with a season alone, kind reads coverage and each row is one episode, carrying episode_id, the number of subtitles the site counts and the languages holding something. With an episode named, kind reads subtitles and each row is a record carrying the id that get_subtitle takes. season is the season the site served and season_requested the one that was asked for, which differ when the newest was read. seasons_available lists the seasons the show holds. A language holding nothing is set aside, the answer comes back unnarrowed, and filters_dropped names it.

get_subtitle

Reads one record from an id list_subtitles returned.

In return: the record, with page_url for the page a reader opens to download the file. read_from reads record here and listing on a row list_subtitles produced, which is what tells an unread field from one the site does not publish: a listing carries no file_name, no size_text and no comment, because the site prints those on a record's own page alone. releases holds the video releases the site published and release_match says whether it published any: stated where it did, none where it did not, so a record marked none says nothing about which video it is timed to. uploader is null on roughly two records out of three. published_at is the site's stamp read into ISO 8601 and carries no timezone, and published_text keeps the site's own wording. rating holds two counters the site publishes, where a zero is a figure it printed.

list_languages

Lists the languages the site catalogues, or the ones one show holds.

In return: each language with the name the site prints, the two-letter site_code it addresses the language by, the BCP 47 code where that mapping is certain, and differs_from_iso. scope says what was measured: catalogue for the whole site, or season when a show id was passed, and count is then the episodes of that season holding the language.

Languages, and the codes the site uses

The site draws twenty-four flags and addresses each language by two letters of its own choosing. Six of them differ from ISO 639-1, and one collides: the site writes br for Brazilian Portuguese, which ISO assigns to Breton.

language keeps the site's own name and language_code carries the tag, so nothing has to be derived from the two letters. list_subtitles accepts a language written any of the three ways.

Configuration

Nothing has to be set. Every variable below is optional.

| TVS_MAX_RETRIES | 3 | 0–8 | A