tmdb-mcp

An MCP server for The Movie Database (TMDB): search and look up movies, TV shows and people, and read IMDb / Rotten Tomatoes / Metacritic ratings (via OMDb) in the same call.

The server speaks standard MCP over stdio, so it works with any MCP client (Claude Desktop/Code, Cursor, VS Code, Cline, …).

Install

Add it to your MCP client's config. The only required credential is a TMDB v4 Read Access Token; OMDB_API_KEY (ratings) and TMDB_LANGUAGE / TMDB_REGION (localization) are optional.

Via npx (no install):

{
  "mcpServers": {
    "tmdb": {
      "command": "npx",
      "args": ["-y", "tmdb-mcp"],
      "env": {
        "TMDB_API_TOKEN": "your-tmdb-v4-read-access-token (required)",
        "OMDB_API_KEY": "your-omdb-key (optional — IMDb/RT/Metacritic ratings)",
        "TMDB_LANGUAGE": "en-US (optional — localize, e.g. ru-RU)",
        "TMDB_REGION": "US (optional — region for certifications, e.g. RU)"
      }
    }
  }
}

Replace each value with your own. Only TMDB_API_TOKEN is required — delete the lines marked optional if you don't need them.

As a .mcpb bundle (easiest for Claude Desktop): download tmdb-mcp.mcpb from the latest release, then open it / drag it into Claude Desktop's Extensions. It's a self-contained bundle (no Node or npm needed); enter the token and the optional fields in the install dialog. Re-download and reinstall to update.

From source: git clone, then npm ci && npm run build, and point the client at it with "command": "node", "args": ["/ABS/PATH/tmdb-mcp/dist/index.js"] and the same env as above.

See docs/clients.md for per-client details and all tunables.

Related MCP server: moviefinder-mcp

What it does

Backbone vs. enrichment. TMDB is the primary source (search, metadata, people, trending). OMDb is optional enrichment: get_movie/get_tv chain the imdb_id TMDB returns into an OMDb lookup so ratings come back in one call. Without an OMDb key the TMDB data still works; the ratings field just reports that it is unconfigured.

Localization. Set TMDB_LANGUAGE (e.g. ru-RU) and TMDB_REGION (e.g. RU) to get localized titles/overviews/genre names and region-specific certifications. Most tools also accept a per-call language override.

Credentials

• TMDB_API_TOKEN (required): a TMDB v4 "Read Access Token" from https://www.themoviedb.org/settings/api. Sent as Authorization: Bearer ….

• OMDB_API_KEY (optional): a free key from https://www.omdbapi.com/apikey.aspx — enables ratings enrichment.

See docs/clients.md for per-client config snippets.

Develop

npm install
npm run build        # type-check + bundle to dist/index.js
npm test             # node:test (mocked, offline)
npm run lint
npm run format
npm run check:api    # live upstream health-check (needs the env credentials)
npm run inspector    # run under the MCP Inspector

Runtime requires Node ≥ 18. Contributor/agent guidance lives in AGENTS.md.

Updating

• .mcpb bundle: download the new bundle from the releases page and reinstall.

• From source: git pull && npm ci && npm run build.

• npx: unpinned npx -y tmdb-mcp fetches the latest on the next run.

This product uses the TMDB API but is not endorsed or certified by TMDB.

License

MIT © Grinv