{
  "markdown": "# TMDB MCP Server\n\n[![npm version](https://img.shields.io/npm/v/tmdb-mcp.svg)](https://www.npmjs.com/package/tmdb-mcp)\n[![CI](https://github.com/Grinv/tmdb-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Grinv/tmdb-mcp/actions/workflows/ci.yml)\n[![license: MIT](https://img.shields.io/npm/l/tmdb-mcp.svg)](LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.Grinv%2Ftmdb--mcp-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Grinv/tmdb-mcp&version=latest)\n[![tmdb-mcp MCP server](https://glama.ai/mcp/servers/Grinv/tmdb-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Grinv/tmdb-mcp)\n\nAn [MCP](https://modelcontextprotocol.io) server for **The Movie Database\n(TMDB)**: search and look up movies, TV shows and people, and read\n**IMDb / Rotten Tomatoes / Metacritic** ratings (via [OMDb](https://www.omdbapi.com/))\nin the same call.\n\nThe server speaks standard MCP over stdio, so it works with any MCP client\n(Claude Desktop/Code, Cursor, VS Code, Cline, …).\n\nOnce it's connected, just ask your agent in natural language (needs a free TMDB\ntoken; see [Getting your credentials](#getting-your-credentials)):\n\n```\n\"Search for the movie Dune: Part Two and show its overview, genres and runtime.\"\n\"What movies are trending this week?\"\n\"Find TV shows similar to Breaking Bad.\"\n\"Who directed Oppenheimer? Show the main cast.\"\n\"What's Greta Gerwig's filmography?\"\n\"Discover highly-rated sci-fi movies from the 2010s, sorted by rating.\"\n\"Where can I stream The Bear in the US?\"\n\"Show me the trailer for Deadpool & Wolverine.\"\n\"List the episodes of Severance season 1.\"\n\"Which movie has IMDb id tt0111161?\"\n\"Search for people named Zendaya.\"\n\"Get the year, genres and rating for these five movies in one go: Dune, Dune: Part Two, Arrival, Sicario and Blade Runner 2049.\"\n\"What are the best limited series to binge over a weekend?\"\n\"What TV shows can I watch with my 9-year-old kid?\"\n\"What movies has A24 produced?\"\n\"What are Tarantino's best-rated crime movies?\"\n\"Who composed the music for My Neighbor Totoro, and what else has he scored?\"\n```\n\nWith an optional (free) **OMDb** key, ratings are added too:\n\n```\n\"What are the IMDb, Rotten Tomatoes and Metacritic scores for The Godfather?\"\n\"Compare the critics' scores for Barbie and Oppenheimer.\"\n```\n\n## Install\n\nAdd it to your MCP client's config. The only required credential is a TMDB v4\n**Read Access Token**; `OMDB_API_KEY` (ratings) and `TMDB_LANGUAGE` / `TMDB_REGION`\n(localization) are optional.\n\n**Via npx (no install):**\n\n```json\n{\n  \"mcpServers\": {\n    \"tmdb\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tmdb-mcp\"],\n      \"env\": {\n        \"TMDB_API_TOKEN\": \"your-tmdb-v4-read-access-token (required)\",\n        \"OMDB_API_KEY\": \"your-omdb-key (optional: IMDb/RT/Metacritic ratings)\",\n        \"TMDB_LANGUAGE\": \"en-US (optional: localize, e.g. ru-RU)\",\n        \"TMDB_REGION\": \"US (optional: region for certifications, e.g. RU)\"\n      }\n    }\n  }\n}\n```\n\n> Replace each value with your own. Only `TMDB_API_TOKEN` is required; delete the\n> lines marked optional if you don't need them.\n\n**As a `.mcpb` bundle (easiest for Claude Desktop):** download `tmdb-mcp.mcpb`\nfrom the [latest release](https://github.com/Grinv/tmdb-mcp/releases/latest),\nthen open it / drag it into Claude Desktop's Extensions. It's a self-contained\nbundle (no Node or npm needed); enter the token and the optional fields in the\ninstall dialog. Re-download and reinstall to update.\n\n**From source:** `git clone`, then `npm ci && npm run build`, and point the client\nat it with `\"command\": \"node\"`, `\"args\": [\"/ABS/PATH/tmdb-mcp/dist/index.js\"]` and\nthe same `env` as above.\n\nSee [docs/clients.md](https://github.com/Grinv/tmdb-mcp/blob/main/docs/clients.md) for per-client details and all tunables.\n\n## What it does\n\n| Tool                                                   | Purpose                                                                                                      |\n| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |\n| `search_movies` / `search_tv` / `search_people`        | Find titles/people by name → TMDB id                                                                         |\n| `search_multi`                                         | Search movies, TV and people at once (each row has a `media_type`)                                           |\n| `get_movie` / `get_tv`                                 | Full details **+ IMDb/RT/Metacritic ratings** (toggle with `include_ratings`)                                |\n| `get_movies` / `get_tv_shows`                          | Compact card(s) (title/year/genres/vote average, ratings opt-in) for 1-20 ids in one call                    |\n| `get_person`                                           | Biography, department, links                                                                                 |\n| `get_movie_credits` / `get_tv_credits`                 | Top-billed cast and headline crew                                                                            |\n| `get_movie_recommendations` / `get_tv_recommendations` | TMDB's editorial recommendations                                                                             |\n| `get_similar`                                          | Algorithmically similar titles (`media_type` + id)                                                           |\n| `get_trending`                                         | What's popular now (movies / TV / people, day or week)                                                       |\n| `get_movie_genres` / `get_tv_genres`                   | Genre id ↔ name reference                                                                                    |\n| `discover_movies`                                      | Filter by genre, year/date range, rating, cast/crew/people, companies, keywords, providers, certification, … |\n| `discover_tv`                                          | Same, plus networks/type/status, but no cast/crew/person filter (use `get_person_credits` for that)          |\n| `get_watch_providers`                                  | Where to stream/rent/buy, by region (JustWatch via TMDB)                                                     |\n| `get_person_credits`                                   | A person's filmography (cast & crew)                                                                         |\n| `get_videos`                                           | Trailers/teasers/clips (YouTube links)                                                                       |\n| `get_reviews`                                          | User reviews (author, rating, text) for a movie/TV                                                           |\n| `get_collection`                                       | A movie franchise/collection and its parts, in release order                                                 |\n| `find_by_imdb_id`                                      | Resolve an IMDb id → TMDB movie/TV/person                                                                    |\n| `get_tv_season` / `get_tv_episode`                     | Season episode list / single-episode details                                                                 |\n| `search_keywords`                                      | Resolve keyword names → ids for `discover_*`                                                                 |\n| `search_companies`                                     | Resolve a production company name → id for `discover_*`'s `with_companies`                                   |\n| `search_watch_providers`                               | Resolve a streaming/rental service name (e.g. 'Netflix') → id for `discover_*`'s `with_watch_providers`      |\n| `get_ratings`                                          | IMDb/RT/Metacritic ratings by IMDb id or title (standalone)                                                  |\n\n**Prompts.** Alongside the tools above, the server exposes two MCP prompts:\n`recommend_similar` (`title`, optional `media_type`, optional `count`) plans a\nsearch for titles similar to one the user liked, driving `get_similar` /\n`get_movie_recommendations` / `get_tv_recommendations` / `discover_movies` /\n`discover_tv` instead of relying on the model's own knowledge. `top_by_entity`\n(`name`, optional `entity_type`, `genre`, `media_type`, `count`) finds the\nbest-regarded titles from a person or a production company/studio (e.g. \"A24's\ntop movies\" or \"Tarantino's best crime films\") via `discover_movies`/\n`discover_tv`, and for a person's TV work specifically falls back to\n`get_person_credits` (TMDB's own `/discover/tv` can't filter by person at all).\n\n**Backbone vs. enrichment.** TMDB is the primary source (search, metadata,\npeople, trending). OMDb is optional enrichment: `get_movie`/`get_tv` chain the\n`imdb_id` TMDB returns into an OMDb lookup, so ratings come back in one call,\nalong with a free-text awards summary (major-award wins/nominations, e.g. Oscars\nfor a film or Emmys for a show, for the title as a whole, not attributed to any\none person) and OMDb's own age rating (`ratings.rated`, separate from this\nserver's own `certification`). Without an OMDb key the TMDB data still works;\nthe `ratings` field just reports that it is unconfigured.\n\n**Localization.** Set `TMDB_LANGUAGE` (e.g. `ru-RU`) and `TMDB_REGION` (e.g.\n`RU`) to get localized titles/overviews/genre names and region-specific\ncertifications. The search tools, `get_movie`/`get_tv`/`get_person`,\n`get_collection` and `discover_movies`/`discover_tv` also accept a per-call\n`language` override.\n\n## Getting your credentials\n\nOne token is required (TMDB); the OMDb key is optional. Both are free.\n\n1. **TMDB token (required).** Create a free account at\n   [themoviedb.org](https://www.themoviedb.org/signup), then open\n   **[Settings → API](https://www.themoviedb.org/settings/api)** and request an API\n   key (personal use). Copy the **\"API Read Access Token\"** (the long v4 token, _not_\n   the short v3 key) into **`TMDB_API_TOKEN`**. It's sent as `Authorization: Bearer …`.\n2. **OMDb key (optional).** Grab a free key at\n   **[omdbapi.com/apikey.aspx](https://www.omdbapi.com/apikey.aspx)** (the free tier\n   is fine), click the activation link in the email, and set **`OMDB_API_KEY`**. This\n   unlocks `get_ratings` and the IMDb / Rotten Tomatoes / Metacritic scores in movie\n   and TV details. Without it, everything else still works.\n\nPut these in your MCP client config's `env` block (see\n[docs/clients.md](https://github.com/Grinv/tmdb-mcp/blob/main/docs/clients.md) for per-client snippets). Never commit them.\n`TMDB_LANGUAGE` / `TMDB_REGION` optionally set default locale/region (e.g. `ru-RU`, `RU`).\n\n### Advanced tuning (env-only, no install-UI equivalent)\n\nSensible defaults; only set these if you know you need to. Env var only, not\nexposed in Claude Desktop's install form, so CLI/Docker users set them directly.\n\n| Variable               | Default                        | Purpose                                            |\n| ---------------------- | ------------------------------ | -------------------------------------------------- |\n| `TMDB_BASE_URL`        | `https://api.themoviedb.org/3` | Override TMDB's API base (e.g. a proxy)            |\n| `OMDB_BASE_URL`        | `https://www.omdbapi.com`      | Override OMDb's API base                           |\n| `HTTP_TIMEOUT_MS`      | `15000`                        | Per-request timeout before aborting                |\n| `HTTP_RETRIES`         | `2`                            | Retries on a transient upstream failure            |\n| `TMDB_MIN_INTERVAL_MS` | `60`                           | Minimum spacing between TMDB requests              |\n| `OMDB_MIN_INTERVAL_MS` | `0`                            | Minimum spacing between OMDb requests              |\n| `CACHE_TTL_MS`         | `300000`                       | How long cached responses stay fresh               |\n| `LOG_LEVEL`            | `info`                         | `debug` \\| `info` \\| `warn` \\| `error` \\| `silent` |\n\nIf TMDB/OMDb is briefly down and a tool falls back to a cached-but-expired\nresponse rather than failing, the result carries\n`_meta: {\"tmdb-mcp/stale\": true}` alongside the normal data, so a client can\ntell a degraded answer from a fresh one.\n\n## Develop\n\n```sh\nnpm install\nnpm run build        # type-check + bundle to dist/index.js\nnpm test             # node:test (mocked, offline)\nnpm run lint\nnpm run format\nnpm run check:api    # live upstream health-check (needs the env credentials)\nnpm run inspector    # run under the MCP Inspector\n```\n\nRuntime requires Node ≥ 20.11. Contributor/agent guidance lives in\n[AGENTS.md](https://github.com/Grinv/tmdb-mcp/blob/main/AGENTS.md).\n\n## Updating\n\n- **`.mcpb` bundle:** download the new bundle from the releases page and reinstall.\n- **From source:** `git pull && npm ci && npm run build`.\n- **npx:** unpinned `npx -y tmdb-mcp` fetches the latest on the next run.\n\nThis product uses the TMDB API but is not endorsed or certified by TMDB.\n\n## Privacy Policy\n\n`tmdb-mcp` runs entirely on your own machine and collects no data of its own.\nSee [PRIVACY.md](PRIVACY.md) for exactly what it sends to TMDB/OMDb and what\n(if anything) it stores locally.\n\n## Security\n\nRead-only, two fixed upstream hosts, credentials never persisted. See\n[SECURITY.md](SECURITY.md) for the full breakdown and how to report a\nvulnerability.\n\n## License\n\n[MIT](LICENSE) © Grinv\n",
  "bytes": 13602,
  "sha": "89f23c3a7760f79f970bfff06d74aad76b4e932f819daf8368e9669f06257795",
  "repo_slug": "grinv/tmdb-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_grinv_tmdb_mcp_443d51e7/readme"
}