tmdb-mcp-server

v0.1.4 pre-1.0

Search movies, TV, and people on The Movie Database (TMDB) — credits, ratings, trailers, images, recommendations, and region-aware streaming availability via MCP. STDIO or Streamable HTTP.

public 8 tools 3 resources protocol 2026-07-28
homeserver.tail54ecf6.ts.net/mcp/02a60b543ac0 
claude mcp add --transport http tmdb-mcp-server https://homeserver.tail54ecf6.ts.net/mcp/02a60b543ac0
codex mcp add tmdb-mcp-server --url https://homeserver.tail54ecf6.ts.net/mcp/02a60b543ac0
{
  "mcpServers": {
    "tmdb-mcp-server": {
      "url": "https://homeserver.tail54ecf6.ts.net/mcp/02a60b543ac0"
    }
  }
}
gemini mcp add --transport http tmdb-mcp-server https://homeserver.tail54ecf6.ts.net/mcp/02a60b543ac0
{
  "mcpServers": {
    "tmdb-mcp-server": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://homeserver.tail54ecf6.ts.net/mcp/02a60b543ac0"
      ]
    }
  }
}
{
  "mcpServers": {
    "tmdb-mcp-server": {
      "type": "http",
      "url": "https://homeserver.tail54ecf6.ts.net/mcp/02a60b543ac0"
    }
  }
}
curl -X POST https://homeserver.tail54ecf6.ts.net/mcp/02a60b543ac0 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'
Built on@cyanheads/mcp-ts-core v0.13.13

Tools

8

tmdb_search_titles

open-world

Search movies, TV shows, and people by name on TMDB. The required first step — TMDB keys on integer ids, not titles, so use this to resolve a name to an id before any detail lookup. Returns ranked results with id, media_type, title/name, year, overview, vote average, resolved genre names, and full poster/profile image URLs. "multi" mode (default) mixes all three entity kinds; "movie"/"tv"/"person" restrict to one type.

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tmdb_search_titles",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Search text — a movie, show, or person name. Required."
    },
    "mode": {
      "default": "multi",
      "description": "What to search. \"multi\" (default) returns mixed movies, shows, and people ranked together — each result carries media_type. \"movie\"/\"tv\"/\"person\" restrict to one type and enable type-specific ranking.",
      "type": "string",
      "enum": [
        "multi",
        "movie",
        "tv",
        "person"
      ]
    },
    "year": {
      "description": "Filter by release/first-air year. Applies to movie and tv modes; ignored for person and multi.",
      "type": "integer",
      "minimum": 1850,
      "maximum": 2100
    },
    "language": {
      "description": "Response language as ISO 639-1, optionally with region (e.g. \"en-US\", \"fr\"). Defaults to the server-configured language.",
      "type": "string"
    },
    "include_adult": {
      "default": false,
      "description": "Include adult-content results. Default false.",
      "type": "boolean"
    },
    "page": {
      "default": 1,
      "description": "Result page (TMDB returns 20 per page). Use to fetch beyond the first 20.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "required": [
    "query",
    "mode",
    "include_adult",
    "page"
  ],
  "additionalProperties": false
}

tmdb_get_movie

Fetch full movie detail by TMDB id in a single call. Returns synopsis, runtime, genres, release date, US certification, budget/revenue, votes, top cast and key crew, YouTube trailers, poster/backdrop URLs, recommendations, similar titles, keywords, and external ids (IMDb, etc.). Sub-resources are folded in via append_to_response — trim the append array to reduce payload. Does not include streaming availability (region-specific) — use tmdb_get_watch_providers for that.

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tmdb_get_movie",
    "arguments": {
      "movie_id": "<movie_id>"
    }
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "movie_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TMDB movie id (integer). Obtain it from tmdb_search_titles (mode \"movie\" or \"multi\") or tmdb_discover_titles."
    },
    "language": {
      "description": "Response language (ISO 639-1[-COUNTRY]). Defaults to the server-configured language.",
      "type": "string"
    },
    "append": {
      "default": [
        "credits",
        "videos",
        "recommendations",
        "similar",
        "keywords",
        "external_ids",
        "release_dates"
      ],
      "description": "Sub-resources to fold into the single request. Defaults to the full set. Trim it to reduce payload when you only need part of the record (e.g. [\"credits\"] for cast only).",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "credits",
          "videos",
          "recommendations",
          "similar",
          "keywords",
          "external_ids",
          "release_dates"
        ]
      }
    }
  },
  "required": [
    "movie_id",
    "append"
  ],
  "additionalProperties": false
}

tmdb_get_show

Fetch full TV show detail by TMDB series id in a single call. Returns overview, genres, first/last air date, status, season and episode counts, creators, networks, season summaries, top cast and key crew, YouTube trailers, US content rating, recommendations, similar shows, keywords, and external ids. The series mirror of tmdb_get_movie; sub-resources fold in via append_to_response. Pass a season_number from seasons[] to tmdb_get_season for the episode list. Does not include streaming availability — use tmdb_get_watch_providers.

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tmdb_get_show",
    "arguments": {
      "series_id": "<series_id>"
    }
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "series_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TMDB TV series id. From tmdb_search_titles (mode \"tv\"/\"multi\") or tmdb_discover_titles."
    },
    "language": {
      "description": "Response language (ISO 639-1[-COUNTRY]). Defaults to the server-configured language.",
      "type": "string"
    },
    "append": {
      "default": [
        "credits",
        "videos",
        "recommendations",
        "similar",
        "keywords",
        "external_ids",
        "content_ratings"
      ],
      "description": "Sub-resources to fold into the single request. Defaults to the full set. Trim to reduce payload (e.g. [\"credits\"]).",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "credits",
          "videos",
          "recommendations",
          "similar",
          "keywords",
          "external_ids",
          "content_ratings"
        ]
      }
    }
  },
  "required": [
    "series_id",
    "append"
  ],
  "additionalProperties": false
}

tmdb_get_season

Fetch the episode list for one season of a TV show. Returns episode names, air dates, overviews, runtimes, vote averages, still URLs, and per-episode guest stars, plus the season's regular recurring cast. Bridges the show-level summary (tmdb_get_show) and per-episode detail. Discover valid season numbers from tmdb_get_show (seasons[].season_number); season 0 is "Specials".

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tmdb_get_season",
    "arguments": {
      "series_id": "<series_id>",
      "season_number": "<season_number>"
    }
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "series_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TMDB TV series id (from tmdb_search_titles or tmdb_get_show)."
    },
    "season_number": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Season number. 0 is the \"Specials\" season on TMDB. Discover valid numbers from tmdb_get_show (seasons[].season_number)."
    },
    "language": {
      "description": "Response language (ISO 639-1[-COUNTRY]). Defaults to the server-configured language.",
      "type": "string"
    }
  },
  "required": [
    "series_id",
    "season_number"
  ],
  "additionalProperties": false
}

tmdb_get_person

Fetch person detail and full filmography by TMDB person id. Returns biography, birth/death dates, place of birth, known-for department, aliases, gender, and the combined_credits filmography split into cast and crew credits (each recency-ordered, most recent first, capped to a display size — totals disclosed). Also returns IMDb id and the extended cross-platform id set (Wikidata, social handles) for chaining.

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tmdb_get_person",
    "arguments": {
      "person_id": "<person_id>"
    }
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "person_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TMDB person id. From tmdb_search_titles (mode \"person\"/\"multi\")."
    },
    "language": {
      "description": "Response language (ISO 639-1[-COUNTRY]). Defaults to the server-configured language.",
      "type": "string"
    }
  },
  "required": [
    "person_id"
  ],
  "additionalProperties": false
}

tmdb_discover_titles

open-world

Filtered, sorted discovery across movies or TV — the power-query entry point. Filter by genre(s), release-year or date range, vote range, vote-count floor, cast/crew (movie), network (tv), watch providers + region, original language, and runtime; sort by popularity, revenue, vote average, vote count, or release date. Genre ids and person/network ids come from search results and other tools. Pair vote_average sorting with vote_count_gte to avoid tiny-sample outliers.

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tmdb_discover_titles",
    "arguments": {
      "media_type": "<media_type>"
    }
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "media_type": {
      "type": "string",
      "enum": [
        "movie",
        "tv"
      ],
      "description": "Discover movies or TV shows. Determines the endpoint and which genre vocabulary applies."
    },
    "sort_by": {
      "default": "popularity.desc",
      "description": "Sort order. \"popularity.desc\" (default) for what is broadly relevant now; \"vote_average.desc\" for critically rated (pair with vote_count_gte to avoid tiny-sample outliers); \"revenue.desc\" for box office; \"primary_release_date.desc\" for newest. For tv, primary_release_date.desc sorts by first-air date; avoid first_air_date.desc — TMDB returns bogus future-dated entries for that sort.",
      "type": "string",
      "enum": [
        "popularity.desc",
        "popularity.asc",
        "revenue.desc",
        "revenue.asc",
        "primary_release_date.desc",
        "primary_release_date.asc",
        "vote_average.desc",
        "vote_average.asc",
        "vote_count.desc",
        "vote_count.asc"
      ]
    },
    "with_genres": {
      "description": "Genre ids to require (AND — all listed genres must match). Genre ids differ between movie and tv; names appear in any result's genres[]. Combine multiple to narrow (e.g. Action + Comedy).",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "without_genres": {
      "description": "Genre ids to exclude (AND — all listed genres are excluded).",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "year": {
      "description": "Exact primary-release year (movie) / first-air year (tv). For a range, use release_date_gte/lte instead.",
      "type": "integer",
      "minimum": 1850,
      "maximum": 2100
    },
    "release_date_gte": {
      "description": "Earliest release/first-air date, inclusive (YYYY-MM-DD). Pair with release_date_lte for a window.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Earliest release date, inclusive (YYYY-MM-DD)."
        }
      ]
    },
    "release_date_lte": {
      "description": "Latest release/first-air date, inclusive (YYYY-MM-DD).",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Latest release date, inclusive (YYYY-MM-DD)."
        }
      ]
    },
    "vote_average_gte": {
      "description": "Minimum average rating (0–10). Use with vote_count_gte so a 10.0 from 3 votes does not dominate.",
      "type": "number",
      "minimum": 0,
      "maximum": 10
    },
    "vote_average_lte": {
      "description": "Maximum average rating (0–10).",
      "type": "number",
      "minimum": 0,
      "maximum": 10
    },
    "vote_count_gte": {
      "description": "Minimum number of votes. The single most useful quality gate — set ~100–1000 to exclude obscure or unrated titles when sorting by vote_average.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "with_cast": {
      "description": "Person ids that must appear in the cast (movie only; silently ignored for tv with a notice). Resolve names to ids with tmdb_search_titles mode \"person\". Multiple ids match any (OR).",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "with_crew": {
      "description": "Person ids that must appear in the crew (movie only; silently ignored for tv with a notice). Useful for \"movies directed by X\". Resolve names to ids with tmdb_search_titles mode \"person\". Multiple ids match any (OR).",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "with_networks": {
      "description": "TV network ids to require (tv only; silently ignored for movie with a notice). Filters to shows that aired on these networks. Known ids: 213 = Netflix, 1024 = Amazon, 2739 = Disney+. Multiple ids match any (OR).",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "with_original_language": {
      "description": "ISO 639-1 original-language code (e.g. \"ja\" for originally-Japanese titles). Distinct from the response language.",
      "type": "string"
    },
    "runtime_gte": {
      "description": "Minimum runtime in minutes.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "runtime_lte": {
      "description": "Maximum runtime in minutes.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "with_watch_providers": {
      "description": "Streaming provider ids to require. MUST be paired with watch_region — provider availability is region-specific. Provider ids come from tmdb_get_watch_providers results. Multiple ids match any (OR).",
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      }
    },
    "watch_region": {
      "description": "Country for with_watch_providers, ISO 3166-1 alpha-2 (e.g. \"US\"). Required when with_watch_providers is set.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "description": "ISO 3166-1 country code (uppercase)."
        }
      ]
    },
    "include_adult": {
      "default": false,
      "description": "Include adult-content results. Default false.",
      "type": "boolean"
    },
    "page": {
      "default": 1,
      "description": "Result page (20 per page).",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "required": [
    "media_type",
    "sort_by",
    "include_adult",
    "page"
  ],
  "additionalProperties": false
}

tmdb_get_watch_providers

open-world

Find where a movie or TV title streams in one region. Returns flatrate (subscription), rent, buy, ads (ad-supported free), and free provider lists with logo URLs, plus the TMDB JustWatch-backed link — the supported path to actual deep links. A region code is REQUIRED: availability is region-specific (JustWatch) and there is no global answer. An empty result for a region is a valid "not available to stream here" answer, not an error.

read
invocation 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tmdb_get_watch_providers",
    "arguments": {
      "media_type": "<media_type>",
      "id": "<id>",
      "watch_region": "<watch_region>"
    }
  }
}
schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "media_type": {
      "type": "string",
      "enum": [
        "movie",
        "tv"
      ],
      "description": "Whether the id is a movie or a TV show."
    },
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "TMDB movie or TV id (matching media_type), from tmdb_search_titles or tmdb_discover_titles."
    },
    "watch_region": {
      "type": "string",
      "pattern": "^[A-Z]{2}$",
      "description": "ISO 3166-1 alpha-2 country code, uppercase (e.g. \"US\", \"GB\", \"DE\"). REQUIRED — streaming availability is region-specific (JustWatch); there is no global answer."
    }
  },
  "required": [
    "media_type",
    "id",
    "watch_region"
  ],
  "additionalProperties": false
}

Resources

3

tmdb-movie

Full movie detail by TMDB id, as injectable context for chat about a specific film. Same enriched record as tmdb_get_movie (all sub-resources appended).

uri tmdb://movie/{movie_id} mime application/json

tmdb-tv

Full TV show detail by TMDB series id, as injectable context for chat about a specific series. Same enriched record as tmdb_get_show (all sub-resources appended).

uri tmdb://tv/{series_id} mime application/json

tmdb-person

Person detail and full filmography by TMDB person id, as injectable context for chat about a specific person. Same enriched record as tmdb_get_person.

uri tmdb://person/{person_id} mime application/json